Odp Net
Odp Net
Odp Net
NET
Developer's Guide
11g Release 1 (11.1.0.7.20)
E15167-01
August 2009
Oracle Data Provider for .NET Developer's Guide 11g Release 1 (11.1.0.7.20)
E15167-01
Copyright © 2002, 2009, Oracle and/or its affiliates. All rights reserved.
Contributing Authors: Janis Greenberg, Riaz Ahmed, Kiminari Akiyama, Shailendra Jain, Ashish Shah,
Lakshminarayanan Suriamoorthy, Steven Caminez, Naveen Doraiswamy, Neeraj Gupta, Sinclair Hsu, Alex
Keh, Chithra Ramamurthy, Martha Woo, Arun Singh, Sujith Somanathan, Nishant Singh
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. 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, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and
license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of
the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software
License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software is developed for general use in a variety of information management applications. It is not
developed or intended for use in any inherently dangerous applications, including applications which may
create a risk of personal injury. If you use this software in dangerous applications, then you shall be
responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use
of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of
this software in dangerous applications.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks
of their respective owners.
This software and documentation may provide access to or information on content, products, and services
from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all
warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and
its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services.
Contents
iii
File Locations After Installation....................................................................................................... 2-2
Windows Registry.............................................................................................................................. 2-3
Configuration File Support............................................................................................................... 2-3
Search Order for Unmanaged DLLs................................................................................................ 2-3
ODP.NET and Dependent Unmanaged DLL Mismatch .............................................................. 2-4
Performance Counters ............................................................................................................................. 2-4
Configuring a Port to Listen for Database Notifications.................................................................. 2-4
General .NET Programming Recommendations and Tips for ODP.NET ..................................... 2-5
iv
Obtaining an OracleRefCursor Object ......................................................................................... 3-58
Obtaining a REF CURSOR Data Type.......................................................................................... 3-58
Populating an OracleDataReader from a REF CURSOR........................................................... 3-58
Populating the DataSet from a REF CURSOR ............................................................................ 3-59
Populating an OracleRefCursor from a REF CURSOR ............................................................. 3-59
Updating a DataSet Obtained from a REF CURSOR ................................................................. 3-59
Behavior of ExecuteScalar Method for REF CURSOR ............................................................... 3-59
Passing a REF CURSOR to a Stored Procedure .......................................................................... 3-60
LOB Support........................................................................................................................................... 3-61
Large Character and Large Binary Data Types .......................................................................... 3-61
Oracle Data Provider for .NET LOB Objects............................................................................... 3-62
Updating LOBs Using a DataSet................................................................................................... 3-63
Updating LOBs Using OracleCommand and OracleParameter .............................................. 3-63
Updating LOBs Using ODP.NET LOB Objects........................................................................... 3-63
Temporary LOBs ............................................................................................................................. 3-64
ODP.NET XML Support....................................................................................................................... 3-64
Supported XML Features ............................................................................................................... 3-64
XQuery Support .............................................................................................................................. 3-65
OracleXmlType and Connection Dependency ........................................................................... 3-66
Updating XMLType Data in the Database .................................................................................. 3-66
Updating XML Data in OracleXmlType ...................................................................................... 3-68
Characters with Special Meaning in XML................................................................................... 3-68
Retrieving Query Result Set as XML............................................................................................ 3-68
Data Manipulation Using XML..................................................................................................... 3-73
Oracle User-Defined Types (UDTs) and .NET Custom Types...................................................... 3-77
Oracle User-Defined Types (UDTs).............................................................................................. 3-78
Custom Types .................................................................................................................................. 3-78
Specifying Custom Type Mappings ............................................................................................. 3-81
Converting Between Custom Types and Oracle UDTs ............................................................. 3-83
Oracle UDT Attribute Mappings .................................................................................................. 3-84
Oracle UDT Retrieval from OracleDataReader .......................................................................... 3-86
Oracle UDT Metadata Retrieval from OracleDataReader......................................................... 3-87
Oracle UDT Parameter Binding with OracleParameter ............................................................ 3-88
Populating the DataSet with Oracle UDTs.................................................................................. 3-90
UDT Method Invocation ................................................................................................................ 3-91
Configuration Settings for Oracle UDTs...................................................................................... 3-91
Oracle Streams Advanced Queuing Support................................................................................... 3-92
Using ODP.NET for Advanced Queuing .................................................................................... 3-94
Database Change Notification Support ........................................................................................... 3-97
Database Change Notification Classes ........................................................................................ 3-99
Supported Operations .................................................................................................................. 3-100
Requirements of Notification Registration................................................................................ 3-101
Using Database Change Notification ......................................................................................... 3-101
Best Practice Guidelines and Performance Considerations .................................................... 3-104
OracleDataAdapter Safe Type Mapping ........................................................................................ 3-104
Comparison Between Oracle Data Types and .NET Types .................................................... 3-104
SafeMapping Property ................................................................................................................. 3-106
v
OracleDataAdapter Requery Property ............................................................................................ 3-108
Guaranteeing Uniqueness in Updating DataSet to Database .................................................... 3-108
What Constitutes Uniqueness in DataRow Objects? ............................................................... 3-109
Configuring PrimaryKey and Constraints Properties ............................................................. 3-109
Updating Without PrimaryKey and Constraints Configuration ........................................... 3-110
Globalization Support ....................................................................................................................... 3-110
Globalization Settings................................................................................................................... 3-110
Globalization-Sensitive Operations............................................................................................ 3-113
Debug Tracing...................................................................................................................................... 3-114
ODP.NET Configuration.................................................................................................................... 3-114
Supported Configuration Settings.............................................................................................. 3-115
Sample Configuration Files ......................................................................................................... 3-122
vi
OracleDataAdapter Constructors .............................................................................................. 5-119
OracleDataAdapter Static Methods............................................................................................ 5-122
OracleDataAdapter Properties.................................................................................................... 5-123
OracleDataAdapter Public Methods .......................................................................................... 5-129
OracleDataAdapter Events .......................................................................................................... 5-134
OracleDatabase Class ......................................................................................................................... 5-138
OracleDatabase Members ............................................................................................................ 5-140
OracleDatabase Constructor........................................................................................................ 5-141
OracleDatabase Properties........................................................................................................... 5-142
OracleDatabase Public Methods ................................................................................................. 5-143
OracleDataReader Class..................................................................................................................... 5-150
OracleDataReader Members........................................................................................................ 5-153
OracleDataReader Static Methods.............................................................................................. 5-157
OracleDataReader Properties ...................................................................................................... 5-158
OracleDataReader Public Methods ............................................................................................ 5-169
OracleError Class................................................................................................................................. 5-214
OracleError Members ................................................................................................................... 5-216
OracleError Static Methods ......................................................................................................... 5-217
OracleError Properties.................................................................................................................. 5-218
OracleError Methods .................................................................................................................... 5-221
OracleErrorCollection Class.............................................................................................................. 5-222
OracleErrorCollection Members ................................................................................................. 5-224
OracleErrorCollection Static Methods ....................................................................................... 5-225
OracleErrorCollection Properties................................................................................................ 5-226
OracleErrorCollection Public Methods ...................................................................................... 5-227
OracleException Class ....................................................................................................................... 5-228
OracleException Members........................................................................................................... 5-230
OracleException Static Methods ................................................................................................. 5-232
OracleException Properties ......................................................................................................... 5-233
OracleException Methods............................................................................................................ 5-236
OracleInfoMessageEventArgs Class ............................................................................................... 5-238
OracleInfoMessageEventArgs Members ................................................................................... 5-240
OracleInfoMessageEventArgs Static Methods ......................................................................... 5-241
OracleInfoMessageEventArgs Properties.................................................................................. 5-242
OracleInfoMessageEventArgs Public Methods ........................................................................ 5-244
OracleInfoMessageEventHandler Delegate................................................................................... 5-245
OracleParameter Class........................................................................................................................ 5-246
OracleParameter Members .......................................................................................................... 5-248
OracleParameter Constructors .................................................................................................... 5-250
OracleParameter Static Methods................................................................................................. 5-261
OracleParameter Properties......................................................................................................... 5-262
OracleParameter Public Methods ............................................................................................... 5-278
OracleParameterCollection Class..................................................................................................... 5-281
OracleParameterCollection Members ........................................................................................ 5-283
OracleParameterCollection Static Methods............................................................................... 5-285
OracleParameterCollection Properties....................................................................................... 5-286
OracleParameterCollection Public Methods ............................................................................. 5-289
vii
OraclePermission Class...................................................................................................................... 5-307
OraclePermission Members......................................................................................................... 5-308
OraclePermission Constructor .................................................................................................... 5-310
OraclePermission Static Methods ............................................................................................... 5-311
OraclePermission Public Properties ........................................................................................... 5-312
OraclePermission Public Methods.............................................................................................. 5-313
OraclePermissionAttribute Class..................................................................................................... 5-316
OraclePermissionAttribute Members ........................................................................................ 5-317
OraclePermissionAttribute Constructor .................................................................................... 5-319
OraclePermissionAttribute Static Methods............................................................................... 5-320
OraclePermissionAttribute Public Properties........................................................................... 5-321
OraclePermissionAttribute Public Methods ............................................................................. 5-322
OracleRowUpdatedEventArgs Class............................................................................................... 5-323
OracleRowUpdatedEventArgs Members.................................................................................. 5-324
OracleRowUpdatedEventArgs Constructor ............................................................................. 5-326
OracleRowUpdatedEventArgs Static Methods ........................................................................ 5-327
OracleRowUpdatedEventArgs Properties ................................................................................ 5-328
OracleRowUpdatedEventArgs Public Methods....................................................................... 5-329
OracleRowUpdatedEventHandler Delegate .................................................................................. 5-330
OracleRowUpdatingEventArgs Class ............................................................................................. 5-331
OracleRowUpdatingEventArgs Members ................................................................................ 5-332
OracleRowUpdatingEventArgs Constructor............................................................................ 5-334
OracleRowUpdatingEventArgs Static Methods....................................................................... 5-335
OracleRowUpdatingEventArgs Properties ............................................................................... 5-336
OracleRowUpdatingEventArgs Public Methods ..................................................................... 5-337
OracleRowUpdatingEventHandler Delegate ................................................................................ 5-338
OracleTransaction Class ..................................................................................................................... 5-339
OracleTransaction Members........................................................................................................ 5-342
OracleTransaction Static Methods .............................................................................................. 5-343
OracleTransaction Properties ...................................................................................................... 5-344
OracleTransaction Public Methods ............................................................................................ 5-346
OracleCollectionType Enumeration .............................................................................................. 5-354
OracleDBShutdownMode Enumeration ...................................................................................... 5-355
OracleDBStartupMode Enumeration ............................................................................................ 5-356
OracleDbType Enumeration ............................................................................................................. 5-357
OracleParameterStatus Enumeration .............................................................................................. 5-359
viii
OracleXmlSaveProperties Constructor ........................................................................................ 6-17
OracleXmlSaveProperties Properties ........................................................................................... 6-18
OracleXmlSaveProperties Public Methods ................................................................................. 6-22
OracleXmlStream Class........................................................................................................................ 6-23
OracleXmlStream Members........................................................................................................... 6-24
OracleXmlStream Constructor ...................................................................................................... 6-26
OracleXmlStream Static Methods ................................................................................................. 6-27
OracleXmlStream Instance Properties ......................................................................................... 6-28
OracleXmlStream Instance Methods ............................................................................................ 6-32
OracleXmlType Class............................................................................................................................ 6-37
OracleXmlType Members .............................................................................................................. 6-38
OracleXmlType Constructors........................................................................................................ 6-40
OracleXmlType Static Methods .................................................................................................... 6-43
OracleXmlType Instance Properties ............................................................................................. 6-44
OracleXmlType Instance Methods ............................................................................................... 6-49
ix
OracleDependency Events............................................................................................................. 9-21
OracleNotificationRequest Class ....................................................................................................... 9-22
OracleNotificationRequest Members ........................................................................................... 9-23
OracleNotificationRequest Static Methods ................................................................................. 9-24
OracleNotificationRequest Properties.......................................................................................... 9-25
OracleNotificationRequest Methods ............................................................................................ 9-29
OracleNotificationEventArgs Class................................................................................................... 9-30
OracleNotificationEventArgs Members ...................................................................................... 9-31
OracleNotificationEventArgs Static Fields.................................................................................. 9-32
OracleNotificationEventArgs Static Methods............................................................................. 9-33
OracleNotificationEventArgs Properties..................................................................................... 9-34
OracleNotificationEventArgs Methods ....................................................................................... 9-39
OnChangeEventHandler Delegate .................................................................................................... 9-40
OracleRowidInfo Enumeration .......................................................................................................... 9-41
OracleNotificationType Enumeration ............................................................................................... 9-42
OracleNotificationSource Enumeration ........................................................................................... 9-43
OracleNotificationInfo Enumeration ................................................................................................ 9-44
x
OracleAQDequeueOptions Properties....................................................................................... 12-12
OracleAQDequeueOptions Public Methods ............................................................................. 12-18
OracleAQEnqueueOptions Class..................................................................................................... 12-19
OracleAQEnqueueOptions Members ........................................................................................ 12-20
OracleAQEnqueueOptions Constructor.................................................................................... 12-21
OracleAQEnqueueOptions Properties....................................................................................... 12-22
OracleAQEnqueueOptions Public Methods ............................................................................. 12-24
OracleAQMessage Class .................................................................................................................... 12-25
OracleAQMessage Members ....................................................................................................... 12-26
OracleAQMessage Constructors................................................................................................. 12-28
OracleAQMessage Properties ..................................................................................................... 12-30
OracleAQMessageAvailableEventArgs Class ............................................................................... 12-38
OracleAQMessageAvailableEventArgs Members ................................................................... 12-39
OracleAQMessageAvailableEventArgs Properties.................................................................. 12-40
OracleAQMessageAvailableEventHandler Delegate .................................................................. 12-47
OracleAQQueue Class ....................................................................................................................... 12-48
OracleAQQueue Members .......................................................................................................... 12-49
OracleAQQueue Constructors .................................................................................................... 12-51
OracleAQQueue Static Methods................................................................................................. 12-55
OracleAQQueue Properties ......................................................................................................... 12-58
OracleAQQueue Public Methods ............................................................................................... 12-64
OracleAQQueue Events ............................................................................................................... 12-78
OracleAQDequeueMode Enumeration .......................................................................................... 12-83
OracleAQMessageDeliveryMode Enumeration ........................................................................... 12-84
OracleAQMessageState Enumeration............................................................................................. 12-86
OracleAQMessageType Enumeration............................................................................................. 12-87
OracleAQNavigationMode Enumeration....................................................................................... 12-88
OracleAQNotificationGroupingType Enumeration .................................................................... 12-89
OracleAQNotificationType Enumeration ...................................................................................... 12-90
OracleAQVisibilityMode Enumeration.......................................................................................... 12-91
xi
OracleClob Members .................................................................................................................... 13-75
OracleClob Constructors.............................................................................................................. 13-78
OracleClob Static Fields ............................................................................................................... 13-80
OracleClob Static Methods .......................................................................................................... 13-81
OracleClob Instance Properties................................................................................................... 13-82
OracleClob Instance Methods ..................................................................................................... 13-88
OracleRefCursor Class ..................................................................................................................... 13-113
OracleRefCursor Members ........................................................................................................ 13-116
OracleRefCursor Static Methods............................................................................................... 13-117
OracleRefCursor Properties....................................................................................................... 13-118
OracleRefCursor Instance Methods.......................................................................................... 13-121
xii
OracleIntervalDS Constructors ................................................................................................. 14-144
OracleIntervalDS Static Fields................................................................................................... 14-149
OracleIntervalDS Static Methods.............................................................................................. 14-151
OracleIntervalDS Static Operators............................................................................................ 14-158
OracleIntervalDS Type Conversions........................................................................................ 14-166
OracleIntervalDS Properties...................................................................................................... 14-169
OracleIntervalDS Methods ........................................................................................................ 14-174
OracleIntervalYM Structure............................................................................................................ 14-177
OracleIntervalYM Members ...................................................................................................... 14-179
OracleIntervalYM Constructors................................................................................................ 14-182
OracleIntervalYM Static Fields ................................................................................................ 14-186
OracleIntervalYM Static Methods ............................................................................................ 14-188
OracleIntervalYM Static Operators .......................................................................................... 14-194
OracleIntervalYM Type Conversions....................................................................................... 14-201
OracleIntervalYM Properties..................................................................................................... 14-204
OracleIntervalYM Methods ....................................................................................................... 14-207
OracleString Structure...................................................................................................................... 14-210
OracleString Members................................................................................................................ 14-212
OracleString Constructors.......................................................................................................... 14-215
OracleString Static Fields ........................................................................................................... 14-220
OracleString Static Methods ...................................................................................................... 14-221
OracleString Static Operators .................................................................................................... 14-226
OracleString Type Conversions ................................................................................................ 14-231
OracleString Properties .............................................................................................................. 14-233
OracleString Methods................................................................................................................. 14-236
OracleTimeStamp Structure............................................................................................................ 14-241
OracleTimeStamp Members ...................................................................................................... 14-243
OracleTimeStamp Constructors................................................................................................ 14-247
OracleTimeStamp Static Fields ................................................................................................. 14-254
OracleTimeStamp Static Methods ............................................................................................ 14-256
OracleTimeStamp Static Operators .......................................................................................... 14-263
OracleTimeStamp Static Type Conversions............................................................................ 14-272
OracleTimeStamp Properties..................................................................................................... 14-278
OracleTimeStamp Methods ....................................................................................................... 14-283
OracleTimeStampLTZ Structure .................................................................................................... 14-294
OracleTimeStampLTZ Members .............................................................................................. 14-296
OracleTimeStampLTZ Constructors ........................................................................................ 14-300
OracleTimeStampLTZ Static Fields.......................................................................................... 14-307
OracleTimeStampLTZ Static Methods..................................................................................... 14-309
OracleTimeStampLTZ Static Operators................................................................................... 14-317
OracleTimeStampLTZ Static Type Conversions .................................................................... 14-326
OracleTimeStampLTZ Properties ............................................................................................. 14-332
OracleTimeStampLTZ Methods ............................................................................................... 14-337
OracleTimeStampTZ Structure....................................................................................................... 14-349
OracleTimeStampTZ Members ................................................................................................. 14-351
OracleTimeStampTZ Constructors........................................................................................... 14-355
OracleTimeStampTZ Static Fields ............................................................................................ 14-367
xiii
OracleTimeStampTZ Static Methods ....................................................................................... 14-369
OracleTimeStampTZ Static Operators ..................................................................................... 14-376
OracleTimeStampTZ Static Type Conversions....................................................................... 14-385
OracleTimeStampTZ Properties ............................................................................................... 14-391
OracleTimeStampTZ Methods .................................................................................................. 14-397
INullable Interface............................................................................................................................ 14-409
INullable Interface Members..................................................................................................... 14-410
INullable Interface Properties .................................................................................................. 14-411
xiv
OracleArrayMappingAttribute Methods .................................................................................. 16-25
IOracleCustomType Interface ........................................................................................................... 16-26
IOracleCustomType Members .................................................................................................... 16-27
IOracleCustomType Interface Methods..................................................................................... 16-28
IOracleCustomTypeFactory Interface.............................................................................................. 16-30
IOracleCustomTypeFactory Members....................................................................................... 16-31
IOracleCustomTypeFactory Interface Methods ....................................................................... 16-32
IOracleArrayTypeFactory Interface ................................................................................................. 16-33
IOracleArrayTypeFactory Members .......................................................................................... 16-34
IOracleArrayTypeFactory Interface Methods........................................................................... 16-35
OracleUdt Class ................................................................................................................................... 16-37
OracleUdt Members...................................................................................................................... 16-38
OracleUDT Static Methods .......................................................................................................... 16-39
OracleRef Class.................................................................................................................................... 16-51
OracleRef Members....................................................................................................................... 16-52
OracleRef Constructors ................................................................................................................ 16-54
OracleRef Static Fields .................................................................................................................. 16-56
OracleRef Static Methods............................................................................................................. 16-57
OracleRef Instance Properties ..................................................................................................... 16-58
Oracle Ref Instance Methods....................................................................................................... 16-62
OracleUdtFetchOption Enumeration .............................................................................................. 16-73
OracleUdtStatus Enumeration .......................................................................................................... 16-74
xv
A Oracle Schema Collections
Common Schema Collections ............................................................................................................... A-1
MetaDataCollections......................................................................................................................... A-1
DataSourceInformation ................................................................................................................... A-2
DataTypes .......................................................................................................................................... A-3
Restrictions ........................................................................................................................................ A-4
ReservedWords ................................................................................................................................ A-5
ODP.NET-Specific Schema Collection ................................................................................................ A-5
Tables .................................................................................................................................................. A-5
Columns ............................................................................................................................................. A-6
Views .................................................................................................................................................. A-6
XMLSchema ...................................................................................................................................... A-7
Users ................................................................................................................................................... A-7
Synonyms .......................................................................................................................................... A-7
Sequences .......................................................................................................................................... A-8
Functions ........................................................................................................................................... A-8
Procedures ......................................................................................................................................... A-9
ProcedureParameters ..................................................................................................................... A-10
Arguments ....................................................................................................................................... A-11
Packages .......................................................................................................................................... A-11
PackageBodies ................................................................................................................................ A-12
JavaClasses ...................................................................................................................................... A-13
Indexes ............................................................................................................................................. A-13
IndexColumns ................................................................................................................................ A-16
PrimaryKeys ................................................................................................................................... A-16
ForeignKeys .................................................................................................................................... A-17
ForeignKeyColumns ...................................................................................................................... A-18
UniqueKeys ..................................................................................................................................... A-18
Glossary
Index
xvi
Preface
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 .NET, or another .NET language.
Although the examples in the documentation and the samples in the sample directory
are written in C#, developers can use these examples as models for writing code in
other .NET languages.
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 to all users, including users that are disabled. 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. Accessibility 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
xvii
accessible to all of our customers. For more information, visit the Oracle Accessibility
Program Web site at http://www.oracle.com/accessibility/.
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 Advanced Application Developer's Guide
■ Oracle Database Application Developer's Guide - Large Objects
■ Oracle Database Oracle Clusterware and Oracle Real Application Clusters Administration
and Deployment Guide
■ Oracle Database New Features
■ Oracle Database Concepts
■ Oracle Database Reference
■ Oracle Database Extensions for .NET Developer's Guide
■ Oracle Database Application Developer's Guide - Object-Relational Features
■ 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 Database Globalization Support Guide
xviii
■ Oracle XML DB Developer's Guide
■ Oracle XML Developer's Kit Programmer's Guide
■ Oracle Database Security Guide
■ Oracle Spatial User's Guide and Reference
■ Oracle Data Guard Concepts and Administration
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/
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://www.oracle.com/technology/documentation/index.html
and
http://msdn.microsoft.com/library
Conventions
The following text conventions are used in this document:
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
xix
xx
What's New in Oracle Data Provider for
.NET?
This section describes new features in Oracle Data Provider for .NET and provides
references 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 11.1.0.7.20
■ New Features in Oracle Data Provider for .NET Release 11.1.0.6.20
■ New Features in Oracle Data Provider for .NET Release 11.1
■ New Features in Oracle Data Provider for .NET Release 10.2.0.4
■ New Features in Oracle Data Provider for .NET Release 10.2.0.3
■ New Features in Oracle Data Provider for .NET Release 10.2.0.2
■ New Features in Oracle Data Provider for .NET Release 10.2
■ 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
xxi
ODP.NET reuses the same fetch array buffer for statements executed
non-concurrently, saving on memory usage. The fetch array buffer stores data
retrieved from the database.
No code changes are necessary to use these features. These features provide better
performance and scalability for ODP.NET applications.
■ Oracle Streams Advanced Queuing Support
ODP.NET supports access to Oracle Streams Advanced Queuing (AQ). AQ
provides database-integrated message queuing functionality to store messages
persistently, propagate messages between queues on different machines and
databases, and transmit messages using Oracle NET services, HTTP, HTTPS and
SMTP.
ODP.NET can access all the operational featuers of AQ, such as enqueue, dequeue,
listen and notification. Oracle Developer Tools for Visual Studio can administer
and manage AQ resources.
See Also:
■ "Support for Code Access Security" on page 3-20
■ "OraclePermission Class" on page 5-307
■ "OraclePermissionAttribute Class" on page 5-316
xxii
receive notifications on which database, service, host, or instance has gone down
or come up. .NET developers can register a callback with ODP.NET to notify the
application when one of these events occurs and subsequently execute an event
handler, as needed.
See Also:
■ Chapter 8, "Oracle Data Provider for .NET HA Event Classes" on
page 8-1
■ "HAEvent" on page 5-111
■ "OracleConnection Properties" on page 5-76
See Also:
■ "OracleDatabase Class" on page 5-138
■ "Shutdown" on page 5-143
■ "Startup" on page 5-147
See Also:
■ "Oracle User-Defined Types (UDTs) and .NET Custom Types" on
page 3-77
■ Chapter 16, "Oracle Data Provider for .NET UDT-Related Classes"
on page 16-1
xxiii
See Also:
■ "Bulk Copy Support" on page 3-28
■ Chapter 17, "Oracle Data Provider for .NET Bulk Copy Classes" on
page 17-1
See Also:
■ "Performance Counters" on page 2-4
■ "Connection Pool Performance Counters" on page 3-7
xxiv
significant performance improvement for the applications that execute the
same statement repeatedly.
This enhancement is transparent to the developer. No code changes are
needed to use this feature.
– Efficient LOB Retrieval with LOBS or SecureFiles
When using LOBS or SecureFiles, this release improves the performance of
small-sized LOB retrieval by reducing the number of round-trips to the
database. SecureFiles is available with Oracle 11g release 1 or later database
versions.
This enhancement is transparent to the developer. No code changes are
needed to use this feature.
xxv
New Features in Oracle Data Provider for .NET Release 10.2.0.2
Oracle Data Provider for .NET release 10.2.0.2 includes the following:
■ Support for Microsoft ADO.NET 2.0, including.
– Provider Factory Classes and Base Classes
Simplifies data access code to access multiple data sources with a provider
generic API.
– Connection String Builder
Makes creating connections strings less error-prone and easier to manage.
– Data Source Enumerator
Enables the application to generically obtain a collection of the Oracle data
sources that the application can connect to.
– Support for Schema Discovery
Permits application developers to find and return database schema
information, such as tables, columns, and stored procedures.
– System.Transactions Support
ODP.NET supports implicit and explicit transactions using the
System.Transactions namespace models.
– Batch Processing Support
Enables batch processing when the OracleDataAdapter.Update method is
called.
See Also:
■ Chapter 4, "Oracle Data Provider for .NET Server-Side Features"
■ Oracle Database Extensions for .NET Developer's Guide
xxvi
Oracle Data Provider for .NET optimizes connection pooling for Oracle RAC
databases by balancing work requests across Oracle RAC instances, based on the
load balancing advisory and service goal. Furthermore, the ODP.NET connection
pool can be enabled to proactively free resources associated with connections that
have been severed due to a down Oracle RAC service, instance, or node.
See Also:
■ "Database Change Notification Support" on page 3-97
■ Chapter 9, "Database Change Notification"
Oracle Data Provider for .NET connection pool management provides explicit
connection pool control to ODP.NET applications. Applications can explicitly clear
connections in a connection pool or all the connection pools.
■ Better LOB performance and functionality with Oracle Database 10g release 2
(10.2) and later
xxvii
These enhancements expose new ADO.NET functionality that was introduced in
Microsoft .NET Framework 1.1.
See Also:
■ "EnlistDistributedTransaction" on page 5-95
■ "HasRows" on page 5-160
See Also:
■ "CommandTimeout" on page 5-15
■ "Cancel" on page 5-27
■ DeriveParameters 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.
xxviii
See Also: "Data Types BINARY_FLOAT and BINARY_DOUBLE"
on page 3-31
xxix
xxx
1
1 Introducing Oracle Data Provider for .NET
This chapter introduces Oracle Data Provider for .NET (ODP.NET), an implementation
of a .NET data provider for Oracle Database.
This chapter contains these topics:
■ .NET Data Access in Oracle: Products and Documentation
■ Overview of Oracle Data Provider for .NET (ODP.NET)
■ Oracle Data Provider for .NET Assembly
■ Using ODP.NET Client Provider in a Simple Application
Oracle Developer Tools for Visual Studio Help describes Oracle Developer Tools. This
help is in the form of dynamic help, which installs as part of the product.
Additionally, the Oracle Developer Tools for Visual Studio Help includes the following
documentation:
■ Oracle Database PL/SQL User's Guide and Reference
■ Oracle Database SQL Reference
■ Oracle Database Extensions for .NET Developer's Guide
■ Oracle Database Error Messages
■ Access to Oracle Data Provider for .NET Dynamic Help
■ Access to Oracle Providers for ASP.NET Dynamic Help
See Also:
■ Oracle Developer Tools for Visual Studio Help
■ Oracle Database Extensions for .NET Developer's Guide for more
information about .NET stored procedures and functions
■ "Oracle Data Provider for .NET Assembly" on page 1-3 for class
listings
■ Chapter 4, "Oracle Data Provider for .NET Server-Side Features"
See Also:
■ Table 4–1, " API Support Comparison Between Client Application
and .NET Stored Procedure"
■ "Oracle Data Provider for .NET Assembly" on page 1-3 for class
lists
■ Chapter 4, "Oracle Data Provider for .NET Server-Side Features"
■ Oracle Database Extensions for .NET Developer's Guide for more
information about .NET stored procedures and functions
Oracle.DataAccess.Client Namespace
The Oracle.DataAccess.Client namespace contains implementations of core
ADO.NET classes and enumerations for ODP.NET, as well as ODP.NET specific
classes.
The following tables list ODP.NET classes, enumerations, and types that are supported
by the Oracle.DataAccess.Client namespace. The tables also indicated which
classes are not supported in .NET stored procedures.
Oracle.DataAccess.Client
Table 1–1 lists the client classes.
Oracle.DataAccess.Client Enumerations
Table 1–2 lists the client enumerations.
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 type structures.
Oracle.DataAccess.Types Exceptions
Type Exceptions are thrown only by ODP.NET type structures. Table 1–4 lists the type
exceptions.
Oracle.DataAccess.Types Classes
Table 1–5 lists the type classes.
Oracle.DataAccess.Types Interfaces
Table 1–6 lists the type interfaces.
Oracle.DataAccess.Types Enumerations
Table 1–7 lists the type enumerations.
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();
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
■ Performance Counters
■ Configuring a Port to Listen for Database Notifications
■ General .NET Programming Recommendations and Tips for ODP.NET
System Requirements
Oracle Data Provider for .NET requires the following:
■ Windows operating system
– 32-bit: Windows Vista (Business, Enterprise, and Ultimate Editions), Windows
Server 2008, Windows Server 2003, Windows Server 2003 R2, Windows 2000
or Windows XP Professional Edition.
Oracle supports 32-bit ODP.NET on x86, AMD64, and Intel EM64T processors
on these operating systems.
– 64 bit: Windows Vista x64 (Business, Enterprise, and Ultimate Editions),
Windows Server 2008 x64, Windows Server 2003 x64, Windows Server 2003 R2
x64, or Windows XP x64.
Oracle supports 32-bit ODP.NET and 64-bit ODP.NET for Windows x64 on
these operating systems.
■ Microsoft .NET Framework 2.0 or later
■ Access to Oracle9i Database Release 2 or later
■ Oracle Client release 11.1 and later and Oracle Net Services (included with
ODP.NET Software)
Additional requirements are the following:
■ Applications using Microsoft Enterprise Services transactions require Oracle
Services for Microsoft Transaction Server release 11.1.
See Also:
■ http://msdn.microsoft.com/netframework
■ http://otn.oracle.com/tech/xml/xdkhome.html to
download the Oracle XML Developer's Kit (XDK)
Additionally, Oracle Data Provider for .NET Dynamic Help is registered with Visual
Studio, providing context-sensitive online help that is seamlessly integrated with
Visual Studio Dynamic Help. With Dynamic Help, the user can access ODP.NET
documentation within the Visual Studio IDE by placing the cursor on an ODP.NET
keyword and pressing the F1 function key.
Oracle Data Provider for .NET creates an entry in the machine.config file of the
computer on which it is installed, for applications using ADO.NET 2.0 and
OracleClientFactory class. This enables the DbProviderFactories class to
recognize ODP.NET.
Windows Registry
Upon installation, ODP.NET creates entries for configuration and tracing within the
Windows Registry. Configuration and tracing registry values apply across all
ODP.NET applications running in that Oracle client installation. Individual ODP.NET
applications can override some of these values by configuring them within the
ODP.NET application itself (for example, FetchSize). The ODP.NET registry values
are located under: HKLM\Software\Oracle\ODP.NET\version\.
Performance Counters
Installing Oracle Data Provider for .NET creates a set of performance counters on the
target system. These performance counters are published by ODP.NET for each
ODP.NET client application. These performance counters can be viewed using
Windows Performance Monitor (Perfmon).
ODP.NET performance counters are published under the following Category Name:
Oracle Data Provider for .NET.
particular port, for example, 1200, an application or web configuration file can be
used as shown below.
<configuration>
<oracle.dataaccess.client>
<settings>
<add name="DbNotificationPort" value="1200"/>
</settings>
</oracle.dataaccess.client>
</configuration>
The port number should be unique for each process running on a computer. Thus, the
port number should be set uniquely for each application either programmatically or
through an application config file. Note that if the specified port number is already in
use, ODP.NET does not provide any errors. For details on configuring ODP.NET, see
"ODP.NET Configuration" on page 3-114.
When the process using ODP.NET starts, the application reads the db notification
port number and listens on that port. Once the port is opened, the port number cannot
be changed during the lifetime of the process.
See Also:
■ "HA Events" on page 3-10
■ "Runtime Connection Load Balancing" on page 3-9
■ "Database Change Notification Support" on page 3-97
■ "Oracle Streams Advanced Queuing Support" on page 3-92
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 Oracle Database
■ ADO.NET 2.0 Features
■ OracleCommand Object
■ ODP.NET Types Overview
■ Obtaining Data from an OracleDataReader Object
■ PL/SQL REF CURSOR and OracleRefCursor
■ LOB Support
■ ODP.NET XML Support
■ Oracle User-Defined Types (UDTs) and .NET Custom Types
■ Oracle Streams Advanced Queuing Support
■ Database Change Notification Support
■ OracleDataAdapter Safe Type Mapping
■ OracleDataAdapter Requery Property
■ Guaranteeing Uniqueness in Updating DataSet to Database
■ Globalization Support
■ Debug Tracing
■ ODP.NET Configuration
The following example uses connection string attributes to connect to Oracle Database:
// C#
using System;
using Oracle.DataAccess.Client;
class ConnectionSample
{
static void Main()
{
OracleConnection con = new OracleConnection();
See Also:
■ "OracleConnection Properties" on page 5-76 for detailed
information on connection attributes
■ "OracleCommand Object" on page 3-30 for detailed information
on statement caching
With this enabled, ODP.NET allows applications to specify the "Data Source"
attribute in the form of:
//host:[port]/[service_name]
See Also: Oracle Net Services Administrator's Guide for details and
requirements in the section Using Easy Connect Naming Method
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:
■ Connection Lifetime
■ Connection Timeout
■ Decr Pool Size
■ HA Events
■ Incr Pool Size
■ Load Balancing
■ Max Pool Size
■ Min Pool Size
■ Pooling
■ Validate Connection
using System;
using Oracle.DataAccess.Client;
class ConnectionPoolingSample
{
static void Main()
{
OracleConnection con = new OracleConnection();
See Also:
■ "ClearPool" on page 5-73
■ "ClearAllPools" on page 5-74
See Also:
■ "Supported Connection String Attributes" on page 5-79
■ "Configuring a Port to Listen for Database Notifications" on
page 2-4
■ Oracle Database Oracle Clusterware and Oracle Real Application
Clusters Administration and Deployment Guide
■ HA Events
When HA (High Availability) events is enabled, Oracle RAC, Data Guard, and
single database instances exhibit the following behavior:
■ ODP.NET connection pool proactively removes connections from the pool
when an Oracle RAC service, service member, node, or database goes down.
■ ODP.NET establishes connections to existing Oracle instances if the removal of
severed connections bring the total number of connections below the "min
pool size".
By default this feature is disabled. To enable HA events, include "HA
Events=true" and "pooling=true" in the connection string.
Note:
The database service being connected to must be configured for AQ_
HA_NOTIFICATIONS. For more details, see Oracle Database Oracle
Clusterware and Oracle Real Application Clusters Administration and
Deployment Guide
See Also:
■ "Supported Connection String Attributes" on page 5-79
■ "Configuring a Port to Listen for Database Notifications" on
page 2-4
■ Oracle Database Oracle Clusterware and Oracle Real Application
Clusters Administration and Deployment Guide
■ Oracle Data Guard Concepts and Administration
Beginning with Oracle Data Provider for .NET release 11.1.0.6.20, all connections,
including those using operating system authentication, can be pooled. Connections are
pooled by default, and no configuration is required, as long as pooling is enabled.
The following example shows the use of operating system authentication:
/* Create an OS-authenticated user in the database
Assume init.ora has OS_AUTHENT_PREFIX set to "" and <OS_USER>
is any valid OS or DOMAIN user.
// C#
using System;
using Oracle.DataAccess.Client;
class OSAuthenticationSample
{
static void Main()
{
OracleConnection con = new OracleConnection();
con.Open();
Console.WriteLine("Connected to Oracle" + con.ServerVersion);
Privileged Connections
Oracle allows database administrators to connect to Oracle Database with either
SYSDBA or SYSOPER privileges. This is done through the DBA Privilege attribute of
the ConnectionString property.
The following example connects scott/tiger as SYSDBA:
// C#
using System;
using Oracle.DataAccess.Client;
class PrivilegedConnectionSample
{
static void Main()
{
OracleConnection con = new OracleConnection();
Password Expiration
Oracle allows users passwords 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 example 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);
Note:
■ The OpenWithNewPassword method should be used only
when the user password has expired, not for changing the
password.
■ If connection pooling is enabled, then invoking the
OpenWithNewPassword method also clears the connection
pool. This closes all idle connections created with the old
password.
Proxy Authentication
With proper setup in the database, proxy authentication enables middle-tier
applications to control the security by preserving database user identities and
privileges, and auditing actions taken on behalf of these users. This is accomplished by
creating and using a proxy database user that connects and authenticates against the
database on behalf of a database user (that is, the real user) or database users.
Proxy authentication can then be used to provide better scalability with connection
pooling. When connection pooling is used in conjunction with proxy authentication,
the proxy authenticated connections can be shared among different real users. This is
because only the connection and session established for the proxy is cached. An
additional session is created for the real user when a proxy authenticated connection is
requested, but it will be destroyed appropriately when the proxy authenticated
connection is placed back into the pool. This design enables the application to scale
well without sacrificing security.
ODP.NET applications can use proxy authentication by setting the "Proxy User Id"
and "Proxy Password" attributes in the connection string. The real user is specified
by the "User Id" attribute. Optionally, to enforce greater security, the real user's
password can be provided through the "Password" connection string attribute.
The following example illustrates the use of ODP.NET proxy authentication:
/* Log on as DBA (SYS or SYSTEM) that has CREATE USER privilege.
Create a proxy user and modified scott to allow proxy connection.
// C#
using System;
using Oracle.DataAccess.Client;
class ProxyAuthenticationSample
{
static void Main()
{
OracleConnection con = new OracleConnection();
See Also:
■ Oracle Database Advanced Application Developer's Guide 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 the ALTER USER statement
■ Oracle Database Security Guide section "Standard Auditing in a
Multitier Environment"
See Also:
■ "Connection String Attributes" on page 3-2
■ "EnlistDistributedTransaction" on page 5-95
See Also:
■ "OracleConnection Properties" on page 5-76
■ "End-to-End Application Tracing" in the Oracle Database
Performance Tuning Guide
■ Oracle Database Security Guide
When a session fails over to another database, the NLS settings that were initially set
on the original session are not carried over to the new session. Therefore, it is the
responsibility of the application to set these NLS settings on the new session.
TAF Notification
Given the delays that failovers can cause, applications may wish to be notified by a
TAF callback. ODP.NET supports the TAF callback function 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.
// 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 */
The Failover event invokes only one event handler. If multiple Failover event
handlers are registered with the Failover event, only the event handler registered
last is invoked.
See Also:
■ Oracle Net Services Administrator's Guide
■ "OracleFailoverEventHandler Delegate" on page 11-9
■ "OracleFailoverEventArgs Class" on page 11-2
See Also:
ADO.NET in the MSDN Library
Table 3–3 ODP.NET Classes that Inherit from ADO.NET 2.0 Base Classes
ODP.NET Classes Inherited from ADO.NET 2.0 Base Class
OracleClientFactory DbProviderFactory
OracleCommand DbCommand
OracleCommandBuilder DbCommandBuilder
OracleConnection DbConnection
OracleConnectionStringBuilder DbConnectionStringBuilder
OracleDataAdapter DbDataAdapter
OracleDataReader DbDataReader
OracleDataSourceEnumerator DbDataSourceEnumerator
OracleException DbException
Table 3–3 (Cont.) ODP.NET Classes that Inherit from ADO.NET 2.0 Base Classes
ODP.NET Classes Inherited from ADO.NET 2.0 Base Class
OracleParameter DbParameter
OracleParameterCollection DbParameterCollection
OracleTransaction DbTransaction
Configuring OraclePermission
The DemandOraclePermission configuration attribute is used to enable or disable
OraclePermission demand for an ODP.NET API. The
DemandOraclePermission value can be specified in the Windows registry or an
individual application configuration file.
The following Windows registry key is used to configure the
DemandOraclePermission configuration attribute:
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\ODP.NET\Assembly_Version\DemandOraclePermission
See Also:
■ "OraclePermission Class" on page 5-307
■ "OraclePermissionAttribute Class" on page 5-316
■ Restrictions
The restrictions that apply to each metadata collection, restricting the scope of the
requested schema information.
■ DataSourceInformation
Information about the instance of the database that is currently being used, such as
product name and version.
■ DataTypes
A set of information about each data type that the database supports.
■ ReservedWords
Reserved words for the Oracle query language.
When the GetSchema method is called, ODP.NET checks the app.config file for the
name of the customized metadata XML file. First, the GetSchema method searches for
an entry in the file with a element named after the provider, in this example,
oracle.dataaccess.client. In this XML element, the value that corresponds to
the name MetaDataXml is the name of the customized XML file, in this example,
CustomMetaData.xml.
If the metadata file is not in the correct directory, then the application loads the default
metadata XML file, which is part of ODP.NET.
scope to Oracle Database 11g release 1 (11.1), or higher. When a second connection is
opened, this transaction is automatically promoted to a distributed transaction. This
functionality provides enhanced performance and scalability.
Connections created within a transaction context, such as TransactionScope or
ServicedComponent, can be established to different versions of Oracle Database.
However, in order to enable the local transaction to be promotable, the following must
be true:
■ The first connection in the transaction context must be established to an Oracle
Database 11g release 1(11.1) instance or higher.
■ All connections opened within the transaction context must have the
"Promotable Transaction" setting set to "promotable". If you try to open
a subsequent connection in the same transaction context with the "Promotable
Transaction" setting set to "local", an exception is thrown.
■ Promoting local transactions requires Oracle Services for Microsoft Transaction
Server 11.1.0.7.20, or higher. If this requirement is not met, then a second
connection request in the same transaction context throws an exception.
Setting "local" as the value of "PromotableTransaction" in the registry,
configuration file (machine/Web/application), or the "Promotable Transaction"
connection string attribute allows only one connection to be opened in the transaction
context, which is associated with a local transaction. Such local transactions cannot be
promoted.
For applications connecting to a pre-Oracle Database 11g release 1 (11.1) instance, refer
to "Local Transaction Support for Older Databases" on page 3-26. This section
describes how ODP.NET behavior can be controlled using the "Promotable
Transaction" setting.
If applications use System.Transactions, it is required that the "enlist"
connection string attribute is set to either "true" (default) or "dynamic".
ODP.NET supports the following System.Transactions programming models for
applications using distributed transactions.
■ Implicit Transaction Enlistment Using TransactionScope
■ Explicit Transaction Enlistment Using CommittableTransaction.
■ Local Transaction Support for Older Databases
Note:
If the first connection is opened to a pre-Oracle Database 11g release 1
(11.1) instance, then the connection enlists as a distributed transaction,
by default.
You can optionally create the transaction as a local transaction by
using the procedure described in "Local Transaction Support for Older
Databases" on page 26. However, these transactions cannot be
promoted to distributed transactions.
Note that the application must call the Complete method on the
TransactionScope object to commit the changes. Otherwise, the transaction is
aborted by default.
// C#
using System;
using Oracle.DataAccess.Client;
using System.Data;
using System.Data.Common;
using System.Transactions;
class psfTxnScope
{
static void Main()
{
int retVal = 0;
string providerName = "Oracle.DataAccess.Client";
string constr =
@"User Id=scott;Password=tiger;Data Source=oracle;enlist=true";
try
{
// Create a TransactionScope object, (It will start an ambient
// transaction automatically).
using (TransactionScope scope = new TransactionScope())
{
// Create first connection object.
using (DbConnection conn1 = factory.CreateConnection())
{
// Set connection string and open the connection. this connection
// will be automatically enlisted in a promotable local transaction.
conn1.ConnectionString = constr;
conn1.Open();
using System;
using Oracle.DataAccess.Client;
using System.Data;
using System.Data.Common;
using System.Transactions;
class psfEnlistTransaction
{
static void Main()
{
int retVal = 0;
string providerName = "Oracle.DataAccess.Client";
string constr =
@"User Id=scott;Password=tiger;Data Source=oracle;enlist=dynamic";
try
{
// Create a committable transaction object.
CommittableTransaction cmtTx = new CommittableTransaction();
– UnquoteIdentifier Method
■ OracleConnection Class Members
– GetSchema Methods
■ OracleDataAdapter Class Members
– UpdateBatchSize Property
– ReturnProviderSpecificTypes Property
■ OracleDataReader Class Members
– HiddenFieldCount Property
– VisibleFieldCount Property
– GetProviderSpecificFieldType Method
– GetProviderSpecificValue Method
– GetProviderSpecificValues Method
■ OracleParameter Class Members
– SourceColumnNullMapping Property
– ResetDbType Method
– ResetOracleDbType Method
■ OracleParameterCollection Class Members
– AddRange Method
The ODP.NET Bulk Copy feature is subject to the same basic restrictions and integrity
constraints for direct path loads, as discussed in the next few sections.
■ ORA_RAW
■ ORA_BFLOAT
■ ORA_BDOUBLE
■ ORA_IBDOUBLE
■ ORA_IBFLOAT
■ ORA_DATE
■ ORA_TIMESTAMP
■ ORA_TIMESTAMP_TZ
■ ORA_TIMESTAMP_LTZ
■ ORA_INTERVAL_DS
■ ORA_INTERVAL_YM
Bulk copy does not support overwrites.
Enabled Constraints
During an Oracle bulk copy, the following constraints are automatically enabled by
default:
■ NOT NULL
■ UNIQUE
■ PRIMARY KEY (unique-constraints on not-null columns)
NOT NULL constraints are checked at column array build time. Any row that violates
the NOT NULL constraint is rejected.
UNIQUE constraints are verified when indexes are rebuilt at the end of the load. The
index is left in an Index Unusable state if it violates a UNIQUE constraint.
Disabled Constraints
During an Oracle bulk copy, the following constraints are automatically disabled by
default:
■ CHECK constraints
■ Referential constraints (FOREIGN KEY)
If the EVALUATE CHECK_CONSTRAINTS clause is specified, then CHECK constraints are
not automatically disabled. The CHECK constraints are evaluated during a direct path
load and any row that violates the CHECK constraint is rejected.
Field Defaults
Default column specifications defined in the database are not available with direct
path loading. Fields for which default values are desired must be specified with the
DEFAULTIF clause. If a DEFAULTIF clause is not specified and the field is NULL, then
a null value is inserted into the database.
See Also: Chapter 17, "Oracle Data Provider for .NET Bulk Copy
Classes"
OracleCommand Object
The OracleCommand object represents SQL statements or stored procedures executed
on Oracle Database.
Note: Optimizer hint syntax in the form --+ ... is not supported.
ODP.NET supports this syntax: /*+ ... */.
Transactions
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 be started only on an
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.
Explicit transactions are required with SQL statements containing "FOR UPDATE" and
"RETURNING" clauses. This is not necessary if global transactions are used.
Parameter Binding
When the DbType property of an OracleParameter object is set, the
OracleDbType property of the OracleParameter object changes accordingly, or
vice versa. The parameter set last prevails.
An application can bind the data and have ODP.NET infer both the DbType and
OracleDbType properties from the .NET type of the parameter value.
ODP.NET allows applications to obtain an output parameter as either a .NET
Framework type or an ODP.NET type. The application can specify which type to
return for an output parameter by setting the DbType property of the output
parameter (.NET type) or the OracleDbType property (ODP.NET type) of the
OracleParameter object. For example, if the output parameter is set as a
DbType.String type by setting the DbType property, the output data is returned as
a .NET String type. On the other hand, if the parameter is set as an
OracleDbType.Char type by setting the OracleDbType property, the output data is
returned as an OracleString type. If both DbType and OracleDbType properties
are set before the command execution, the last setting takes affect.
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.
When binding by position (default) to a function, ODP.NET expects the return value to
be bound first, before any other parameters.
This section describes the following:
■ Data Types BINARY_FLOAT and BINARY_DOUBLE
■ OracleDbType Enumeration Type
■ Inference of DbType, OracleDbType, and .NET Types
■ PL/SQL Associative Array Binding
■ Array Binding
See Also:
■ "GetDouble" on page 5-177
■ "GetFloat" on page 5-179
Inference of DbType and OracleDbType from Value In the OracleParameter class, Value
is an object type that can be of any .NET Framework data type or ODP.NET type. If the
OracleDbType and DbType properties of the OracleParameter class are not
specified, the OracleDbType property is inferred from the type of the Value
property.
Table 3–7 shows the inference of DbType and OracleDbType properties from the
Value property when the type of Value is one of the .NET Framework data types.
Table 3–7 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
IOracleCustomType Object Object
Single Single Single
String String Varchar2
TimeSpan TimeSpan IntervalDS
Note: Using other .NET Framework data types as values for the
OracleParameter class without specifying either the DbType or
the OracleDbType properties raises an exception because
inferring DbType and OracleDbType properties from other .NET
Framework data types is not supported.
Table 3–8 shows the inference of DbType and OracleDbType properties from the
Value property when type of Value is one of Oracle.DataAccess.Types.
Table 3–8 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
Table 3–8 (Cont.) Inference of DbType and OracleDbType from Value (ODP.NET Types)
Value
(Oracle.DataAccess.Types) System.Data.DbType OracleDbType
OracleRef Object Ref
OracleRefCursor Object RefCursor
OracleString String Varchar2
OracleTimeStamp DateTime TimeStamp
OracleTimeStampLTZ DateTime TimeStampLTZ
OracleTimeStampTZ DateTime TimeStampTZ
OracleXmlType String XmlType
■ DATE
■ NCHAR
■ NUMBER
■ NVARCHAR2
■ RAW
■ ROWID
■ UROWID
■ VARCHAR2
Using unsupported data types with associative arrays can cause an ORA-600 error.
connect scott/tiger@oracle
CREATE TABLE T1(COL1 number, COL2 varchar2(20));
// C#
using System;
using System.Data;
using Oracle.DataAccess.Client;
class AssociativeArraySample
{
static void Main()
{
OracleConnection con = new OracleConnection();
Param1.Direction = ParameterDirection.Input;
Param2.Direction = ParameterDirection.InputOutput;
Param3.Direction = ParameterDirection.Output;
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 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");
prm.Direction = ParameterDirection.Input;
prm.Value = myArrayDeptNo;
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.
// C#
using System;
using System.Data;
using Oracle.DataAccess.Client;
class ArrayBindExceptionSample
{
static void Main()
{
OracleConnection con = new OracleConnection();
con.ConnectionString = "User Id=scott;Password=tiger;Data Source=oracle;";
con.Open();
// 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};
prm.Direction = ParameterDirection.Input;
prm.Value = myArrayDeptNo;
txn.Commit();
}
cmd.Parameters.Clear();
cmd.CommandText = "select count(*) from depttest";
Statement Caching
Statement caching eliminates the need to parse each SQL or PL/SQL statement before
execution by caching server cursors created during the initial statement execution.
Subsequent executions of the same statement can reuse the parsed information from
the cursor, and then execute the statement without reparsing, for better performance.
In order to see performance gains from statement caching, Oracle recommends
caching only those statements that will be repeatedly executed. Furthermore, SQL or
PL/SQL statements should use parameters rather than literal values. Doing so takes
full advantage of statement caching, because parsed information from parameterized
statements can be reused even if the parameter values change in subsequent
executions. However, if the literal values in the statements are different, the parsed
information cannot be reused unless the subsequent statements also have the same
literal values.
If the Statement Cache Purge attribute 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 of.
Self-Tuning
ODP.NET applications can be self-tuned for performance optimization. ODP.NET
dynamically monitors application queries during runtime.
Note: Self-tuning for applications does not take place if the Pooling
connection string attribute is set to false. Self-tuning is also not
supported inside .NET stored procedures.
The maximum number of statements that can be cached per connection is determined
by the MaxStatementCacheSize configuration attribute. The
MaxStatementCacheSize value can be specified in the Windows registry or XML
configuration file.
The MaxStatementCacheSize setting is useful in limiting the number of cached
statements, as well as the number of open cursors. This is because a cached statement
equates to a cursor being opened on the server. For this reason, you should not set
If self-tuning is disabled for an application, then the value of statement cache size is
determined by the settings in the connection string, configuration file, or the registry. If
statement cache size is not specified in any of these sources, then the default value of
statement cache size is set to 0. To have ODP.NET configured with the same default
settings as previous releases of ODP.NET, disable self-tuning and set the
StatementCacheSize value to 10.
<oracle.dataaccess.client>
<settings>
<add name="SelfTuning" value="1"/>
</settings>
</oracle.dataaccess.client>
</configuration>
See Also:
■ "OracleDataAdapter Class" on page 5-114
■ "OracleDataReader Class" on page 5-150
■ 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 type. 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 type. If a value in the column cannot be
represented as a System.Decimal type, then an exception is raised.
The Fill method of the OracleDataAdapter class uses the OracleDataReader
object 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.
See Also:
■ "OracleDataReader Class" on page 5-150
■ "OracleDataAdapter Class" on page 5-114
■ "Item" on page 5-162
■ "GetFieldType" on page 5-178
■ "GetValues" on page 5-210
■ "GetValue" on page 5-209
See Also: "ODP.NET Types Overview" on page 3-46 for a list of all
ODP.NET types
Table 3–12 lists the valid type accessors that ODP.NET uses to obtain ODP.NET types
for an Oracle native type.
Setting InitialLONGFetchSize to -1
By setting InitialLONGFetchSize to -1, it is possible to fetch the entire LONG or
LONG RAW data from the database for a select query, without requiring a primary key,
ROWID, or unique column in the select list.
When InitialLONGFetchSize is set to -1, the entire LONG or LONG RAW data is
retrieved and cached during Read method invocations on the OracleDataReader
object. Calls to GetString, GetOracleString, GetChars, GetBytes, or
GetOracleBinary in the OracleDataReader return the entire column data.
Obtaining Additional Data Prior to Oracle Database 10g Release 2 (10.2) With releases prior to
Oracle Database 10g release 2 (10.2), obtaining data beyond InitialLOBFetchSize
characters or bytes requires one of the following in the query 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 LOB data is fetched from the database when the appropriate typed
accessor method is called on the OracleDataReader object.
To be able to fetch the entire LOB data without having a primary key column, a
ROWID, or unique columns in the select list, set the size of the
InitialLOBFetchSize property on the OracleCommand object to equal or greater
than the number of characters or bytes needed to be retrieved.
Obtaining Additional Data From Oracle Database 10g Release 2 (10.2) and Later Starting with
Oracle Database 10g release 2 (10.2), the entire LOB data is returned when a typed
accessor is invoked, regardless of the value set to the InitialLOBFetchSize
property. Primary key, ROWID, or unique columns are not required to be in the query
select list to obtain data beyond the specified InitialLOBFetchSize.
The GetOracleBlob, GetOracleClob, GetOracleBlobForUpdate, and
GetOracleClobForUpdate methods can now be invoked even if
InitialLOBFetchSize is greater than 0, starting with Oracle Database 10g release
2.
The following is a complete list of typed accessor methods that an application can call
for the CLOB and BLOB columns if InitialLOBFetchSize is set to a value greater
than 0:
■ Methods callable for BLOB column
– GetBytes
– GetValue
– GetValues
– GetOracleBinary
– GetOracleBlob
– GetOracleBlobForUpdate
– GetOracleValue
– GetOracleValues
■ Methods callable for CLOB column
– GetChars
– GetString
– GetValue
– GetValues
– GetOracleString
– GetOracleClob
– GetOracleClobForUpdate
– GetOracleValue
– GetOracleValues
Setting InitialLOBFetchSize to -1
By setting InitialLOBFetchSize to -1, it is possible to fetch the entire LOB data
from the database for a select query, without requiring a primary key, ROWID, or
unique column in the select list. When InitialLOBFetchSize is set to -1, the entire
LOB column data is fetched and cached during the Read method invocations on the
OracleDataReader object. Calls to GetString, GetOracleString, GetChars,
GetBytes, or GetOracleBinary in the OracleDataReader allow retrieving all
data.
Methods Supported for InitialLOBFetchSize of -1 This section lists supported and not
supported methods for the CLOB and BLOB data types when the
InitialLOBFetchSize property is set to -1.
Table 3–13 lists supported and not supported methods for the CLOB data types.
Table 3–14 lists supported and not supported methods for the BLOB data types.
See Also:
■ "LOB Support" on page 3-61
■ "InitialLOBFetchSize" on page 5-18
■ "InitialLONGFetchSize" on page 5-20
Oracle Database 10g Release 2 (10.2) and Later An application does not have to choose
between performance and OracleBlob and OracleClob functionality. Setting the
InitialLOBFetchSize property results in a performance boost and still gives the
flexibility to use the OracleBlob and OracleClob objects.
If the size of the LOB data is unknown or if the LOB data size varies irregularly, then it
is better to leave the InitialLOBFetchSize property to its default value of 0. This
still gives better performance in most cases.
Setting the InitialLOBFetchSize property to a size equal to or greater than the
LOB data size for most rows improves performance. It is generally recommended that
the InitialLOBFetchSize property 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 the InitialLOBFetchSize property to 1 KB.
See Also:
■ "LOB Support" on page 3-61
■ "InitialLOBFetchSize" on page 5-18
■ "InitialLONGFetchSize" on page 5-20
Use of FetchSize
The FetchSize property represents the total memory size in bytes that ODP.NET
allocates to cache the data fetched from a database round-trip.
The FetchSize property can be set either on the OracleCommand or the
OracleDataReader object, depending on the situation. Additionally, the
FetchSize property of the OracleCommand object is inherited by the
OracleDataReader object and can be modified.
If the FetchSize property is set on the OracleCommand object, then the newly
created OracleDataReader object inherits the FetchSize property of the
OracleCommand object. This inherited FetchSize value 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 property. All subsequent fetches from the
database use the same cache allocated for that OracleDataReader object. Therefore,
changing the FetchSize value 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 database round-trip for better performance. For
example, if a query returns 100 rows and each row takes 1024 bytes, then setting the
FetchSize property to 102400 takes just one database round-trip to fetch 100 rows.
For the same query, if the FetchSize property is set to 10240, it takes 10 database
round-trips to retrieve 100 rows. If the application requires all the rows to be fetched
from the result 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 because it fetches only 10 rows, not 100 rows.
Setting FetchSize Value at Design Time If the row size for a particular SELECT statement is
already known from a previous execution, the FetchSize value of the
OracleCommand object can be set at design time to the result of multiplying that row
size times the number of rows the application wishes to fetch for each database
round-trip. The FetchSize value set on the OracleCommand object is inherited by
the OracleDataReader object that is created by the ExecuteReader method
invocation on the OracleCommand object. Rather than setting the FetchSize value
on the OracleCommand object, the FetchSize value can also be set on the
OracleDataReader object directly. In either case, the FetchSize value is set at
design time, without accessing the RowSize property value at run time.
Setting FetchSize Value at Run Time 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 object, 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 object to the
product of the RowSize property value multiplied by the number of rows the
application wishes to fetch for each database round-trip. In this scenario, the
FetchSize property is set by accessing the RowSize property at run time.
// C#
using System;
using Oracle.DataAccess.Client;
using System.Data;
class InRefCursorParameterSample
{
static void Main()
{
OracleConnection conn = new OracleConnection
("User Id=scott; Password=tiger; Data Source=oracle");
// Bind another Number parameter to get the REF Cursor column value
OracleParameter outNumPrm = cmd.Parameters.Add("outNumPrm",
OracleDbType.Int32, DBNull.Value, ParameterDirection.Output);
LOB Support
ODP.NET provides an easy and optimal way to access and manipulate large object
(LOB) data types.
Note: LONG and LONG RAW data types are made available for
backward compatibility in Oracle9i, but should not be used in new
applications.
The ODP.NET LOB objects can be obtained by calling the proper typed accessor on the
OracleDataReader object, or by calling the proper typed accessor 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 BFILE types) 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 database round-trip. The OracleClob object 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.
Additional methods 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 of.
If an ODP.NET LOB object is obtained from an OracleDataReader object through a
typed accessor, then its Connection property is set with a reference to the same
OracleConnection object used by the OracleDataReader object. 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
object. 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 be used only within
the context of the same OracleConnection referenced by the ODP.NET LOB object.
For example, the ODP.NET LOB Connection property must reference the same
connection as the OracleCommand object 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.
Temporary LOBs
Temporary LOBs can be instantiated for BLOB, CLOB, and NCLOB objects. 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, an anonymous
PL/SQL block, or a stored procedure.
■ To act as the source or the destination of data transfer between two LOB objects as
in the CopyTo operation.
■ Store XML data natively in the database as the Oracle database native type,
XMLType.
■ Access relational and object-relational data as XML data from an Oracle Database
instance into the Microsoft .NET environment, and process the XML using the
Microsoft .NET Framework.
■ Save changes to the database using XML data.
■ Execute XQuery statements.
For the .NET application developer, these features include the following:
■ Enhancements to the OracleCommand, OracleConnection, and
OracleDataReader classes.
■ The following XML-specific classes:
– OracleXmlType
OracleXmlType objects are used to retrieve Oracle native XMLType data.
– OracleXmlStream
OracleXmlStream objects are used to retrieve XML data from
OracleXmlType objects as a read-only .NET Stream object.
– OracleXmlQueryProperties
OracleXmlQueryProperties objects represent the XML properties used by
the OracleCommand class when the XmlCommandType property is Query.
– OracleXmlSaveProperties
OracleXmlSaveProperties objects represent the XML properties used by
the OracleCommand class when the XmlCommandType property is Insert,
Update, or Delete.
See Also:
■ "OracleCommand Class" on page 5-2
■ "OracleXmlType Class" on page 6-37
■ "OracleXmlStream Class" on page 6-23
■ "OracleXmlQueryProperties Class" on page 6-3
■ "OracleXmlSaveProperties Class" on page 6-13
■ Oracle XML DB Developer's Guide
XQuery Support
Beginning with Oracle Database 10g release 2(10.2), ODP.NET supports the XQuery
language through a native implementation of SQL/XML functions, XMLQuery and
XMLTable. When executing XQuery statements, Oracle XML DB generally evaluates
XQuery expressions by compiling them into the same underlying structures as
relational queries. Queries are optimized, leveraging both relational-database and
XQuery-specific optimization technologies, so that Oracle XML DB serves as a native
XQuery engine.
properly. The OracleDataAdapter object uses any custom SQL INSERT, UPDATE, or
DELETE statements that are provided. Otherwise, valid SQL statements are generated
by the OracleCommandBuilder object as needed to flush the changes to the
database.
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 an OracleXmlType object, having an
instance of an OracleXmlType class 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 object that a
NULL value is to be inserted.
Passing in a null OracleXmlType object as an input parameter does not insert a
NULL value into the XMLType column. In this case, the OracleCommand object
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 value or by not inserting anything into that column as in the following
examples:
insert into xml_table(xmltype_col) values(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);
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. A blank 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.
Table 3–17 Date and Time Format Handling When Retrieving Data
Database Release Date and Time Format Supported
Oracle9i release 2 (9.2.x) and Oracle DATE type data is retrieved in the format specified using
Oracle Database 10g 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 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 statement 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
Oracle Database 10g release The generated XML DATE and TIMESTAMP formats are based on
2 (10.2) or later the standard XML Schema formats.
For more information on the XML Schema specification, see
http://www.w3.org/TR/2004/REC-xmlschema-2-20041
028/datatypes.html#isoformats
// C#
using System;
using System.Data;
using System.Xml;
using Oracle.DataAccess.Client;
class QueryResultAsXMLSample
{
static void Main()
{
xmlDocument.PreserveWhitespace = true;
xmlDocument.Load(xmlReader);
Console.WriteLine(xmlDocument.OuterXml);
The following XML document is generated for that table: The XML entity encoding
that represents the angle brackets appears in bold.
<?xml version = '1.0'?>
<ROWSET>
<ROW>
<id>1</id >
<NAME><Jones></NAME>
</ROW>
</ROWSET>
Note that the element name for the Id column matches the case of the column name.
The SQL query, SELECT * FROM EMP_TABLE, generates the following XML document:
<?XML version="1.0"?>
<ROWSET>
<ROW>
<EMPLOYEE_ID>205</EMPLOYEE_ID>
<LAST_NAME>Higgins</LAST_NAME>
</ROW>
</ROWSET>
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.
This section demonstrates how Oracle database handles the mapping of SQL
identifiers to XML element names, when retrieving query results as XML from the
database. The demonstration uses the 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 column named some id that contains a
blank space character. The space character is not allowed in an XML element name.
When retrieving the query results as XML, 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 is converted to a sequence of hexadecimal digits, derived from the Unicode
encoding of the characters, bracketed by an introductory underscore, a lowercase x,
and a trailing underscore.
Thus, 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 You can improve the default mapping of SQL identifiers to
XML element names by using 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. Prefix the
aliases with an at sign (@) to map them to XML attributes instead of XML
elements.
■ Modify the XML document. Use Extensible Stylesheet Language Transformation
(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 may have an impact on
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, as shown in the following example:
// 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')));
</EMPLIST>
</ROW>
</ROWSET>
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, which appears in bold in the example.
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.
Table 3–18 Date and Time Format Handling When Saving Data
Database Release Date and Time Format Supported
Oracle9i release 2 (9.2.x) and All DATE, TIMESTAMP, and TIMESTAMP WITH TIME ZONE type
Oracle Database 10g 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
Oracle Database 10g release The generated XML DATE and TIMESTAMP formats are based on
2 (10.2) or later the standard XML Schema formats.
For more information on the XML Schema specification, see
http://www.w3.org/TR/2004/REC-xmlschema-2-20041
028/datatypes.html#isoformats
ODP.NET cannot accept a single XML document and determine which are insert,
update, or delete changes.
The insert change must be in an XML document containing only rows to be inserted,
the update changes only with rows to be updated, and the delete changes 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;
To change the name of employee 205 from Higgins to Smith, specify the
employees table and the XML data containing the changes as follows:
<?xml version = '1.0'?>
<ROWSET>
<ROW>
<EMPLOYEE_ID>205</EMPLOYEE_ID>
<LAST_NAME>Smith</LAST_NAME>
</ROW>
</ROWSET>
The following XML document can be used to insert values (1, '<Jones>') into the
specialchars table. The XML entity encoding that represents the angle brackets
appears in bold.
<?xml version = '1.0'?>
<ROWSET>
<ROW>
<id>1</id >
<NAME><Jones></NAME>
</ROW>
</ROWSET>
The following XML document can be used to insert values (1, Smith) into the
casesensitive_table:
<?xml version = '1.0'?>
<ROWSET>
<ROW>
<Id>1</Id>
<NAME>Smith</NAME>
</ROW>
</ROWSET>
Note that the element name for the Id column matches the case of the column name.
Note that the specialchars table has a column named some id that contains a
blank space character. The space character is not allowed in an XML element name.
<some_x0020_id>2</some_x0020_id>
<NAME><Jones></NAME>
</ROW>
</ROWSET>
// C#
using System;
using System.Data;
using System.Xml;
using Oracle.DataAccess.Client;
class InsertUsingXmlDocSample
{
static void Main()
{
OracleConnection con = new OracleConnection();
ucols[0] = "some_x0020_id";
ucols[1] = "NAME";
cmd.XmlSaveProperties.UpdateColumnsList = ucols;
// Insert rows
int rows = cmd.ExecuteNonQuery();
Improving Default Mapping You can improve the default mapping by using 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 may have an impact on 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 save changes to multiple relational tables that have been
joined together. Oracle recommends that you create a view on those relational tables,
and then update that view. If the view cannot be updated, triggers can be used instead.
See Also: Oracle Database SQL Reference for the description and
syntax of the CREATE VIEW statement
Commit Transactions
When the changes in an XML document are made, either all the changes are
committed, or if an error occurs, all changes are rolled back.
The term UDT is used interchangeably with Oracle object types and abstract data
types (ADTs).
The name of the Oracle UDT is case-sensitive and must be in the form schema_
name.type_name.
UDT samples are provided in the ORACLE_BASE\ORACLE_
HOME\ODP.NET\Samples\UDT directory.
Custom Types
Oracle Data Provider for .NET supports UDTs by representing Oracle UDTs defined in
the database as .NET types, that is, custom types. For every Oracle UDT that the
application wishes to fetch and manipulate, one custom type factory and one custom
type are needed. The custom factory class is solely responsible for instantiating the
custom type. ODP.NET uses the interfaces implemented on the custom factory classes
to instantiate custom types at run time. Custom types define the mapping between the
Oracle UDT attributes or elements to the .NET members. ODP.NET uses the interfaces
implemented on the custom type instances to transfer values between the Oracle UDT
and the custom type at run time.
Custom types can be .NET classes or structures. They can represent either Oracle
Objects or Oracle Collections. Custom types can be implemented manually by the
application developer or generated through an ODP.NET code generation tool.
Once the factory class and the custom type are defined and meet the implementation
requirements, the application may set ODP.NET to automatically discover the
mapping between the Oracle UDT and the custom type. This discovery process is
based on the attribute that is applied on the custom factory class. Alternatively, the
application can provide an explicit mapping through a configuration file.
Oracle Collections can be represented as an array of .NET Types. For example, an
Oracle Collection type of NUMBER can be mapped to an int[]. Moreover, an Oracle
Collection type of an Oracle UDT can be mapped to an array of the custom type.
Custom types must adhere to certain requirements in order for ODP.NET to represent
Oracle UDTs as custom types. These requirements are as follows:
– OracleArrayMappingAttribute
This attribute specifies the custom type member that stores the elements of an
Oracle collection for custom types representing Oracle collections.
The attribute must be specified on only one of the custom type members.
See Also:
■ "IOracleCustomType Interface" on page 16-26
■ "OracleRef Class" on page 16-51
■ "IOracleCustomTypeFactory Interface" on page 16-30
See Also: Oracle Developer Tools for Visual Studio help sections on
User-Defined Types Node, under Server Explorer for Visual Studio
2005 and Oracle Explorer for Visual Studio 2003, for further
information on UDT mapping
Required Attributes
■ factoryName
The case-sensitive assembly qualified name of the custom type factory class or
struct.
If the assembly that defines the custom type factory does not have a strong name,
then a partial assembly name consisting of just the assembly name is sufficient. In
the case of strongly named assemblies, a complete assembly name is required. It
must include the assembly name, the Version, Culture, PublicKeyToken.
■ typeName
The case-sensitive name of the UDT defined in the database. By default all UDTs
are created in the database with upper case names
■ schemaName
The case-sensitive schema in which the UDT is defined in the database. By default
all schemas are created in the database with upper case names
Optional Attributes
■ dataSource
If specified, indicates that the custom type mapping applies only to Oracle UDTs
defined in the database that the application connects to, as specified by the TNS
name alias.
The Data Source is case-insensitive.
The following is an example of the format of the XML that can be specified in the
configuration file for .NET 2.0:
<oracle.dataaccess.client>
<settings>
<add name="Person" value="udtMapping factoryName='Sample.PersonFactory,
Sample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'
typeName='PERSON' schemaName='SCOTT' dataSource='oracle'"/>
<add name="Student" value="udtMapping factoryName='Sample.StudentFactory,
Sample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'
typeName='STUDENT' schemaName='SCOTT'"/>
</settings>
</oracle.dataaccess.client>
Table 3–19 Attribute Mappings Between UDTs and Custom Object Types
Type of UDT Attribute or Element .NET Type ODP.NET Type
BFILE #1 System.Byte[] OracleBFile
BINARY FLOAT System.Byte, OracleDecimal
System.Int16,
System.Int32,
System.Int64,
System.Single,
System.Double,
System.Decimal
Table 3–19 (Cont.) Attribute Mappings Between UDTs and Custom Object Types
Type of UDT Attribute or Element .NET Type ODP.NET Type
BINARY DOUBLE System.Byte, OracleDecimal
System.Int16,
System.Int32,
System.Int64,
System.Single,
System.Double,
System.Decimal
BLOB System.Byte[] OracleBlob
CHAR System.Char[], OracleString
System.String
CLOB System.Char[], OracleClob
System.String
DATE System.DateTime OracleDate
INTERVAL DAY TO SECOND System.TimeSpan, OracleIntervalDS
INTERVAL YEAR TO MONTH System.Int64 OracleIntervalYM
LONG RAW System.Byte[] OracleBinary
NCHAR System.Char[], OracleString
System.String
NCLOB System.Char[], OracleClob
System.String
Nested Table custom type, .NET ODP Type[]
type[], or custom
type[]
NUMBER System.Byte, OracleDecimal
System.Int16,
System.Int32,
System.Int64,
System.Single,
System.Double,
System.Decimal
NVARCHAR2 System.Char[], OracleString
System.String
Object Type custom type N/A
RAW System.Byte[] OracleBinary
REF System.String OracleRef
TIMESTAMP System.DateTime OracleTimeStamp
TIMESTAMP WITH LOCAL TIME ZONE System.DateTime OracleTimeStampL
TZ
TIMESTAMP WITH TIME ZONE System.DateTime OracleTimeStampT
Z
VARCHAR2 System.Char[], OracleString
System.String
VARRAY custom type, .NET ODP Type[]
type[], or custom
type[]
XMLTYPE System.Char[], OracleXmlType
System.String
Notes:
1. Conversion from a System.Byte[] to a BEFILE is not supported, and therefore,
System.Byte[] only represents a BFILE in read-only scenarios.
Table 3–20 (Cont.) Type and Value Returned from OracleDataReader Object
OracleDataReader NULL Value
method/property Column Custom Type Value Returned for Returned for
invocation Data Type Mapping Oracle UDT Oracle UDT
GetProviderSpecificV Collection schema.type custom object[] null
alue(), | .NET Type[] |
GetProviderSpecificV PS object[]
alues(),
GetOracleValue(),
GetOracleValues()
GetProviderSpecificV REF none | OracleRef OracleRef.Nul
alue(), schema.type l
GetProviderSpecificV
alues(),
GetOracleValue(),
GetOracleValues(),
GetOracleRef()
GetOracleString() REF none | OracleString OracleString.
schema.type (HEX) Null
Note: The UdtTypeName may differ from the Oracle UDT specified
in the custom type mapping. This occurs when the parameter type is a
super type of the Oracle UDT that the custom type represents.
■ In case of Input/Output binding, the behavior is the same as Input and Output
parameters.
■ For Input parameter values, the bind value is converted to the UDT specified by
the custom type mapping.
■ For Output parameters:
– If the value being returned is an Oracle Object or Collection, it is converted to
a custom type or array type as specified by the custom type mapping. The
value returned is always a custom type or an array type, regardless of whether
the property most recently set was DbType or OracleDbType.
– If the value being returned is a REF, then no custom type mapping is required.
Table 3–22 describes the valid ways of binding input parameters for Oracle UDTs.
The last column indicates the Oracle type that ODP.NET converts the
OracleParameter value to before binding.
Table 3–22 Valid Ways to Bind Input Parameters for Oracle UDTs
OracleParameter.
DbType or
OracleParameter. OracleParameter. OracleParameter Custom Type Oracle Type converted to
Value OracleDbType . UdtTypeName Mappings before Binding
custom object | DbType.Object | not set none | Exception thrown
custom OracleDbType.Object schema.type
object[] |.NET | OracleDbType.Array
object[] |PS | OracleDbType.Ref |
object[] |
String (HEX) |
OracleString(H
EX) | OracleRef
custom DbType.Object | schema.type none Exception thrown
object[] |.NET OracleDbType.Object
object[] |PS | OracleDbType.Array
object[]
custom object DbType.Object schema.type schema.type Specified UDT is
instantiated. Value is bound
as Object or Collection,
based on the UdtTypeName
property
custom object OracleDbType.Object schema.type schema.type Specified UDT is
instantiated. schema.type
must represent an object.
custom object OracleDbType.Array schema.type schema.type Specified UDT is
instantiated. schema.type
must represent a collection.
.NET object[] DbType.Object | schema.type schema.type UDT specified by
| PS object[] OracleDbType.Array OracleParameter.UdtT
| custom ypeName is instantiated.
object[]
.NET object[] OracleDbType.Object schema.type none | Exception thrown
| PS object[] schema.type
| custom
object[]
custom object OracleDbType.Ref schema.type none | Exception thrown
|.NET object[] schema.type
|PS object[]
custom
object[]
String (HEX) | DbType.Object | schema.type none | Exception thrown
OracleString OracleDbType.Object schema.type
(HEX) | | OracleDbType.Array
OracleRef
Char[] (HEX) | OracleDbType.Ref schema.type none | A REF
String (HEX) schema.type
|OracleString
(HEX) |
OracleRef
Table 3–23 Valid Ways to Bind Output Parameters for Oracle UDTs
OracleParame
Type returned ter. Custom Type
from Oracle OracleParameter. DbType UdtTypeName Mappings Type converted to
Object/Collec DbType.Object | not set none | Exception thrown
tion/REF OracleDbType.Object | schema.type
OracleDbType.Array |
OracleDbType.Ref
Object/Collec DbType.Object | schema.type none Exception thrown
tion OracleDbType.Object |
OracleDbType.Array
Object DbType.Object | schema.type schema.type custom object
OracleDbType.Object
Object OracleDbType.Array | schema.type none | Exception thrown
OracleDbType.Ref schema.type
Collection OracleDbType.Array | schema.type schema.type custom object |
DbType.Object custom object[] |
.NET object[] |
PS object[]
Collection OracleDbType.Ref | schema.type none | Exception thrown
OracleDbType.Object schema.type
REF DbType.Object | schema.type none | Exception thrown
OracleDbType.Object | schema.type
OracleDbType.Array
REF OracleDbType.Ref schema.type none | OracleRef
schema.type
See Also:
■ "Parameter Binding" on page 3-31
■ "Typed OracleDataReader Accessors" on page 3-48
Table 3–24 Types that Populate the DataSet with ADO.NET 2.0
Oracle ReturnProvider- DataSet
Column SpecificTypes Custom Type DataSet Column Column Null
Type Property Mappings DataSet Column Type Value Value
Object / False/True none Exception thrown Exception thrown Exception
Collection thrown
Object / False schema.type typeof(custom custom object DbNull.Val
Collection type) ue
Object / True schema.type typeof(custom custom object custom
Collection type) object.Nul
l
Collection False schema.type typeof(custom .NET type[] | PS DbNull.Val
type[])| object[] | custom ue
typeof(.NET object[]
type[]) |
typeof(PS type[])
Collection True schema.type typeof(custom .NET type[] | PS null
type[])| object[] | custom
typeof(.NET object[]
type[]) |
typeof(PS type[])
REF False none | typeof(string) string/HEX DbNull.Val
schema.type ue
REF True none | typeof(OracleRef) OracleRef OracleRef.
schema.type Null
StatementCacheWithUdts
StatementCacheWithUdts specifies whether or not ODP.NET caches Oracle UDTs
retrieved by a SELECT statement along with the statement when it is returned to the
statement cache. Possible values are 1 - Yes (the default) or 0 - No.
For the value of 1, the Oracle UDTs are cached along with the statements. Therefore,
the memory that contained the UDTs can be re-used; subsequent executions of the
same statement do not require additional memory. This may result in an overall higher
performance.
For the value of 0, ODP.NET frees the memory for the retrieved Oracle UDTs before
the statement is returned to the statement cache. This may result in poorer
performance because subsequent executions will require new memory allocations.
UdtCacheSize
UdtCacheSize specifies the size of the object cache for each connection that
ODP.NET uses when retrieving and manipulating Oracle UDTs. The value for this
setting must be specified in kilobytes (KB) with the default 4096KB, equivalent to 4
MB.
This configuration setting is used to determine how frequently the objects in the object
cache will be purged (using an LRU approach) as the limit of the object cache size
approaches.
See Also: Oracle Streams Advanced Queuing User's Guide and Reference
See Also:
■ "Recipients" on page 12-35
■ "OracleAQAgent Class" on page 12-2
■ Enqueue
Messages are enqueued when producer applications push the messages into a
queue. This is accomplished by calling the Enqueue method on an
OracleAQQueue object. Multiple messages can be enqueued using the
EnqueueArray method.
See Also:
■ "Enqueue" on page 12-68
■ "EnqueueArray" on page 12-70
■ Dequeue
Messages are dequeued when consumer applications pull the messages from a
queue. This is accomplished by calling the Dequeue method on an
OracleAQQueue object. Multiple messages can be dequeued using the
DequeueArray method.
See Also:
■ "Dequeue" on page 12-64
■ "DequeueArray" on page 12-66
■ Listen
Subscriber applications can use a Listen call to monitor multiple queues for
subscriptions on different queues. This is a more scalable solution for cases where
a subscriber application has subscribed to many queues and wishes to receive
messages that arrive in any of the queues.
■ Notification
Subscriber applications can utilize the notification mechanism to get notifications
about message availability in a queue. The applications can decide to skip or
dequeue the message from the queue based on the information received.
A subscriber application must register for event notification on the queues from
which it wants to receive notifications. This is represented by the
MessageAvailable event on OracleAQQueue. The event is triggered when
messages matching the subscriptions arrive.
Notifications can be registered as regular or grouping notifications. A time out
value for these notifications can also be specified. Various notification options can
be set using the OracleAQQueue.Notification property. Notifications set on
an OracleAQQueue object gets cancelled automatically when the object gets
disposed.
See Also:
■ "MessageAvailable Event" on page 12-78
■ "Notification" on page 12-61
■ Buffered Messaging
Buffered messaging was introduced in Oracle Streams AQ 10g Release 2 (10.2). In
buffered messaging, messages reside in a shared memory area. This makes it faster
than persistent messaging. The messages are written to disk only when the total
memory consumption of buffered messages approaches the available shared
memory limit. Buffered messaging is ideal for applications that do not require the
reliability and transaction support of Oracle Streams AQ persistent messaging.
Buffered and persistent messages use the same single-consumer or
multi-consumer queues, and the same administrative and operational interfaces.
They are distinguished from each other by a delivery mode parameter. When an
application enqueues a message to an Oracle Streams AQ queue, it sets the
delivery mode parameter as well.
The delivery mode parameter can be set on OracleAQMessage by modifying the
DeliveryMode property. Buffered messaging is supported in all queue tables
created with compatibility 8.1 or higher.
------------------------------------------------------------------
-- SQL to grant appropriate privilege to database user, SCOTT
------------------------------------------------------------------
SQL> ALTER USER SCOTT ACCOUNT UNLOCK IDENTIFIED BY Pwd4Sct;
User altered.
SQL> GRANT ALL ON DBMS_AQADM TO scott;
------------------------------------------------------------------
-- PL/SQL to create queue-table and queue and start queue for SCOTT
------------------------------------------------------------------
BEGIN
DBMS_AQADM.CREATE_QUEUE_TABLE(
queue_table=>'scott.test_q_tab',
queue_payload_type=>'RAW',
multiple_consumers=>FALSE);
DBMS_AQADM.CREATE_QUEUE(
queue_name=>'scott.test_q',
queue_table=>'scott.test_q_tab');
DBMS_AQADM.START_QUEUE(queue_name=>'scott.test_q');
END;
/
------------------------------------------------------------------
-- PL/SQL to stop queue and drop queue & queue-table from SCOTT
------------------------------------------------------------------
BEGIN
DBMS_AQADM.STOP_QUEUE('scott.test_q');
DBMS_AQADM.DROP_QUEUE(
queue_name => 'scott.test_q',
auto_commit => TRUE);
DBMS_AQADM.DROP_QUEUE_TABLE(
queue_table => 'scott.test_q_tab',
force => FALSE,
auto_commit => TRUE);
END;
/
-- End of Part I, database setup.
namespace ODPSample
{
/// <summary>
/// Demonstrates Enqueuing and Dequeuing raw message
/// using a single consumer queue
/// </summary>
class EnqueueDequeue
{
static void Main(string[] args)
{
// Create connection
string constr = "user id=scott;password=Pwd4Sct;data source=oracle";
OracleConnection con = new OracleConnection(constr);
// Create queue
OracleAQQueue queue = new OracleAQQueue("scott.test_q", con);
try
{
// Open connection
con.Open();
// Prepare to Enqueue
queue.EnqueueOptions.Visibility = OracleAQVisibilityMode.OnCommit;
// Enqueue message
queue.Enqueue(enqMsg);
// Prepare to Dequeue
queue.DequeueOptions.Visibility = OracleAQVisibilityMode.OnCommit;
queue.DequeueOptions.Wait = 10;
// Dequeue message
OracleAQMessage deqMsg = queue.Dequeue();
Using Continuous Query Notification, an application can maintain the validity of the
client-side cache (for example, the ADO.NET DataSet) easily.
Using the notification framework, applications can specify a query result set as a
registered query for notification request on the database, and create this notification
registration to maintain the validity of the query result set. When there is a change on
the database that could affect the client-side cache's query results, the notification
framework notifies the application.
Based on the information provided by the invalidation message, the application can
then act accordingly. For example, the application might need to refresh its own copy
of the data for the registered query that is stored locally in the application.
By default, Windows Vista and Windows XP Service Pack 2 and later enable the
Windows Firewall to block virtually all TCP network ports to incoming connections.
Therefore, for Continuous Query Notification to work properly on these operating
systems, the Windows Firewall must be configured properly to allow specific
executables to open specific ports.
See Also: Oracle Database Platform Guide for Windows for details on
configuring the Windows Firewall
Beginning with Oracle Database 11g and ODP.NET 11g (11.1), Database Change
Notification queries can be query-based (default) or object-based. The query-based
registrations allow ODP.NET to notify applications when the selected rows have
changed in the database. The object-based registrations allow ODP.NET to notify
applications for any changes that occur in the table(s) containing the selected rows.
Query-based notifications are supported only when all the following are true:
1. The Oracle database version is at least 11.1.
2. The select list contains no other column data types other than VARCHAR2 and
NUMBER.
See Also:
■ "Configuring a Port to Listen for Database Notifications" on
page 2-4
■ Oracle Database Advanced Application Developer's Guide for further
details on the requirements for Continuous Query Notification
See Also:
■ "OracleDependency Class" on page 9-2
■ "OracleNotificationRequest Class" on page 9-22
■ "OracleNotificationEventArgs Class" on page 9-30
Supported Operations
The ODP.NET notification framework in conjunction with Continuous Query
Notification supports the following activities:
■ Creating a notification registration by:
– Creating an OracleDependency instance and binding it to an
OracleCommand instance.
■ Grouping multiple notification requests into one registration by:
– Using the OracleDependency.AddCommandDependency method.
– Setting the OracleCommand.Notification request using the same
OracleNotificationRequest instance.
■ Registering for Database Change Notification by:
– Executing the OracleCommand. If either the notification property is null or
NotificationAutoEnlist is false, the notification will not be made.
■ Removing notification registration by:
– Using the OracleDependency.RemoveRegistration method.
– Setting the Timeout property in the OracleNotificationRequest
instance before the registration is created.
– Setting the IsNotifiedOnce property to true in the
OracleNotificationRequest instance before the registration is created.
The registration is removed once a database notification is sent.
■ Ensuring Change Notification Persistence by:
– Specifying whether or not the invalidation message is queued persistently in
the database before delivery. If an invalidation message is to be stored
persistently in the database, then the change notification is guaranteed to be
sent. If an invalidation message is stored in an in-memory queue, the change
notification can be received faster, however, it could be lost upon database
shutdown or crashes.
■ Retrieving notification information including:
– The changed object name.
– The schema name of the changed object.
– Database events that cause the notification, such as insert, delete, and so on.
– The RowID of the modified object row.
In Oracle SQL, the ROWIDTOCHAR(ROWID) and ROWIDTONCHAR(ROWID)
functions convert a ROWID value to VARCHAR2 and NVARCHAR data types,
respectively.
If these functions are used within a SQL statement, ROWIDs are not returned in
the OracleNotificationEventArgs object that is passed to the database
change notification callback.
■ Defining the listener port number.
By default, the static OracleDependency.Port property is set to -1. This
indicates that the ODP.NET listens on a port that is randomly picked when
ODP.NET registers a database change notification request for the first time during
the execution of an application.
ODP.NET creates only one listener that listens on one port within an application
domain. Once ODP.NET starts the listener, the port number cannot be changed;
Changes to the static OracleDependency.Port property will generate an error
if a listener has already been created.
See Also:
■ "OracleCommand Class" on page 5-2
■ "Notification" on page 5-21
■ "NotificationAutoEnlist" on page 5-22
■ "OracleDependency Class" on page 9-2
■ "OracleNotificationEventArgs Class" on page 9-30
Application Steps
The application should do the following:
1. Create an OracleDependency instance.
2. Assign an event handler to the OracleDependency.OnChange event property if
the application wishes to have an event handler invoked when database changes
are detected. Otherwise, the application can choose to poll on the HasChanges
property of the OracleDependency object. This event handler is invoked when
the change notification is received.
3. Set the port number for the listener to listen on. The application can specify the
port number for one notification listener to listen on. If the application does not
specify a port number, a random one is used by the listener.
try
{
con = new OracleConnection(constr);
OracleCommand cmd = new OracleCommand("select * from emp", con);
con.Open();
// Set the port number for the listener to listen for the notification
// request
OracleDependency.Port = 1005;
con.Close();
// Loop while waiting for notification
while(MyNotificationSample.IsNotified == false)
{
Thread.Sleep(100);
}
}
}
}
precision. The Oracle INTERVAL DAY TO SECOND type can represent values in units of
e-9, and the .NET TimeSpan type can represent only values in units of e-7.
Table 3–29 lists the maximum and minimum values for Oracle INTERVAL DAY TO
SECOND and .NET DateTime types.
SafeMapping Property
The OracleDataAdapter Safe Type Mapping feature prevents data loss when
populating Oracle data for any of these types into a .NET DataSet. 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
By default, Safe Type Mapping is disabled.
Note:
■ Database table column names are case-sensitive.
■ Column names in the hash table that correspond to invalid
column names are ignored.
SafeTyping 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";
// Create the adapter with the selectCommand txt and the connection string
OracleDataAdapter adapter = new OracleDataAdapter(cmdstr, constr);
See Also:
■ "Requery" on page 5-125
■ "SelectCommand" on page 5-126
3. If a set of columns that meets the following criteria is returned in the select list, a
UniqueConstraint object is added to the DataTable.Constraints
collection, but the DataTable.PrimaryKey property 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
property.
Additionally, the OracleDataAdapter.FillSchema method performs as follows:
■ Setting the DataTable.PrimaryKey property implicitly creates a
UniqueConstraint object.
■ If a column is part of the DataTable.PrimaryKey property or the
UniqueConstraint object, or both, it will be repeated for each occurrence of the
column in the select list.
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.
Globalization Settings
An OracleGlobalization object can be used to represent the following:
■ Client Globalization Settings
■ Session Globalization Settings
■ Thread-Based Globalization Settings
using System;
using Oracle.DataAccess.Client;
class ClientGlobalizationSample
{
static void Main()
{
OracleGlobalization ClientGlob = OracleGlobalization.GetClientInfo();
using System;
using Oracle.DataAccess.Client;
class SessionGlobalizationSample
{
static void Main()
{
OracleConnection con = new OracleConnection();
The following example 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);
// Print "12/01/1999"
Console.WriteLine(date.ToString());
}
}
Globalization-Sensitive Operations
This section lists ODP.NET types and operations that are dependent on or sensitive to
globalization settings.
See Also:
■ "OracleDataAdapter Safe Type Mapping" on page 3-104
■ Chapter 10, "Oracle Data Provider for .NET Globalization
Classes"
■ Chapter 14, "Oracle Data Provider for .NET Types Structures"
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 SQL statements modified by the
provider
■ Connection pooling statistics such as enlistment and delistment
■ Thread ID (entry and exit)
■ HA Events and Load Balancing information
■ Distributed Transactions
■ Self-tuning information
■ User-mode dumps upon unmanaged exceptions
To enable ODP.NET for tracing, TraceFileName, TraceLevel, and TraceOption
must be set appropriately either in the Windows Registry or in an XML configuration
file.
ODP.NET Configuration
The settings for specific versions of ODP.NET can be configured several ways for
specific effects on precedence:
■ The Windows registry entries are machine-wide settings for a particular version of
ODP.NET.
■ The machine.config settings are .NET framework-wide settings that override
the Windows registry values.
■ The application or web config file settings are application-specific settings that
override the machine.config settings and the Windows registry settings.
■ Any attribute settings that are equivalent to the connection string override
everything.
The application or web config file can be useful and sometimes essential in scenarios
where more than one application on a computer use the same version of ODP.NET, but
each application needs a different ODP.NET configuration. The Windows registry
value settings for a given version of ODP.NET affect all the applications that use that
version of ODP.NET. However, having ODP.NET configuration values in the
application or web config file assure that these settings are applied only for that
application, thus providing more granularity.
For example, if the application or web.config file has a StatementCacheSize
configuration setting of 100, this application-specific setting forces the version of
ODP.NET that is loaded by that application to use 100 for the StatementCacheSize
and overrides any setting in the machine.config and in the registry. Note that for
any setting that does not exist in a config file (machine.config or application/web
config), the value in the registry for a loaded version of ODP.NET is used, as in
previous releases.
Note that ODP.NET reads the machine.config files from the version of the .NET
Framework on which ODP.NET runs, not from the version of ODP.NET.
ODP.NET only reads the Windows Registry and the XML configuration file when it is
loaded into memory, thus any configuration changes made after that are not read or
used until the application is re-started.
Note: The default values shown are the values used for an attribute
if the registry key does not exist or if it is not configured anywhere.
Server-Side Features
This chapter discusses server-side features provided by Oracle Data Provider for .NET.
With the support for .NET stored procedures in Oracle Databases for Windows that
Oracle Database Extensions for .NET provides, ODP.NET can be used to access Oracle
data through the implicit database connection that is available from the context of the
.NET stored procedure execution. Explicit user connections can also be created to
establish connections to the database that hosts the .NET stored procedure or to other
Oracle Databases.
See Also:
■ Oracle Database Extensions for .NET Developer's Guide for more
information about how to create .NET Stored procedures
■ Table 4–1, " API Support Comparison Between Client Application
and .NET Stored Procedure" on page 4-6
Only one implicit database connection is available within a .NET stored procedure
invocation. To establish more connections in addition to the implicit database
connection, an explicit connection must be created. When the Close method is
invoked on the OracleConnection that represents the implicit database connection,
the connection is not actually closed. Therefore, the Open method of the same or
another OracleConnection object can be invoked to obtain the connection that
represents the implicit database connection.
The implicit database connection can only be acquired by the Open method invocation
by a native Oracle thread that initially invokes the .NET stored procedure. However,
threads spawned from the native Oracle thread can use implicit database connections
that are obtained by the native Oracle thread.
Transaction Support
The .NET stored procedure execution automatically inherits the current transaction on
the implicit database connection. No explicit transaction can be started, committed, or
rolled back inside a .NET stored procedure on a Context connection. However, explicit
transaction can be started, committed, or rolled back inside a .NET stored procedure
on a Client connection.
For example, OracleConnection.BeginTransaction is not allowed inside a
.NET stored procedure for a context connection, but is allowed for a client connection.
.NET stored procedures do not support distributed transactions. If you have enlisted a
client connection in a distributed transaction and call a .NET stored procedure or
function, an error occurs.
If a .NET stored procedure or function performs operations on the database that are
required to be part of a transaction, the transaction must be started prior to calling the
.NET stored procedure. Any desired commit or rollback must be performed after
returning from the .NET stored procedure or function.
The following example consists of a client application and a .NET stored procedure,
InsertRecordSP, that inserts an employee record into an EMP table.
"empno", OracleDbType.Int32 );
EmpNoPrm.Direction = ParameterDirection.Input;
EmpNoPrm.Value = 7950;
OracleParameter EmpNamePrm = Cmd.Parameters.Add(
"ename", OracleDbType.Varchar2, 10 );
EmpNamePrm.Direction = ParameterDirection.Input;
EmpNamePrm.Value = "Bernstein";
// Execute .NET stored procedure
Cmd.ExecuteNonQuery();
Console.WriteLine( "Number of record(s) before COMMIT {0}",
RecordCount() );
Txn.Commit();
Console.WriteLine( "Number of record(s) after COMMIT {0}",
RecordCount() );
}
catch( OracleException OE )
{
Console.WriteLine( OE.Message );
}
finally
{
// Cleanup objects
if( null != Txn )
Txn.Dispose();
if( null != Cmd )
Cmd.Dispose();
if( null != Conn && Conn.State == ConnectionState.Open )
Conn.Close();
}
}
static int RecordCount()
{
int EmpCount = 0;
OracleConnection Conn = null;
OracleCommand Cmd = null;
try
{
Conn = new OracleConnection( "User Id=scott;Password=tiger;" +
"Data Source=oracle;" );
Conn.Open();
Cmd = new OracleCommand( "SELECT COUNT(*) FROM EMP", Conn );
Object o = Cmd.ExecuteScalar();
EmpCount = Convert.ToInt32(o.ToString());
}
catch( OracleException OE )
{
Console.WriteLine( OE.Message );
}
finally
{
if( null != Cmd )
Cmd.Dispose();
}
return EmpCount;
}
}
Column Headings
The column heading for this table are:
Client application: The client application.
Implicit connection: The implicit database connections in a .NET stored procedure.
Explicit connection: The explicit user connections in a .NET stored procedure.
Table 4–1 API Support Comparison Between Client Application and .NET Stored
Procedure
Implicit
Connection/
Client Explicit
Class or Class Members Application Connection
OnChangeEventHandler Delegate
-all members Yes No/No
OracleDependency Class
-all members Yes No/No
OracleNotificationEventArgs Class
-all members Yes No/No
OracleNotificationRequest Class
-all members Yes No/No
OracleFailoverEventArgs Class
-all members Yes No/No
OracleFailoverEventHandler Delegate
-all members Yes No/No
OracleTransaction Class
-all members Yes No/No
OracleCommand Class
-Transaction Property Yes No #1/No #1
Table 4–1 (Cont.) API Support Comparison Between Client Application and .NET Stored
Procedure
Implicit
Connection/
Client Explicit
Class or Class Members Application Connection
OracleConnection Class
-ConnectionTimeout Property Yes Yes #3/Yes
-DataSource Property Yes Yes #2/Yes
-BeginTransaction Method Yes No/No
-ChangeDatabase Method No No/No
-Clone Method Yes No/Yes
-EnlistDistributedTransaction Method Yes No/No
-OpenWithNewPassword Method Yes No/Yes
-Failover Event Yes No/No
-OracleFailoverEventHandler Delegate Yes No/No
ODP.NET Enumerations
-FailoverEvent Enumeration Yes No/No
-FailoverReturnCode Enumeration Yes No/No
-FailoverType Enumeration Yes No/No
-OracleNotificationInfo Enumeration Yes No/No
-OracleNotificationSource Enumeration Yes No/No
-OracleNotificationType Enumeration Yes No/No
This chapter describes the following Oracle Data Provider for .NET classes.
■ OracleCommand Class
■ OracleCommandBuilder Class
■ OracleConnection Class
■ OracleDataAdapter Class
■ OracleDatabase Class
■ OracleDataReader Class
■ OracleError Class
■ OracleErrorCollection Class
■ OracleException Class
■ OracleInfoMessageEventArgs Class
■ OracleInfoMessageEventHandler Delegate
■ OracleParameter Class
■ OracleParameterCollection Class
■ OraclePermission Class
■ OraclePermissionAttribute Class
■ OracleRowUpdatedEventArgs Class
■ OracleRowUpdatedEventHandler Delegate
■ OracleRowUpdatingEventArgs Class
■ OracleRowUpdatingEventHandler Delegate
■ OracleTransaction Class
■ OracleCollectionType Enumeration
■ OracleDBShutdownMode Enumeration
■ OracleDBStartupMode Enumeration
■ OracleDbType Enumeration
■ OracleParameterStatus Enumeration
OracleCommand Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.ComponentModel.Component
System.Data.Common.DbCommand (ADO.NET 2.0 only)
Oracle.DataAccess.Client.OracleCommand
Declaration
// ADO.NET 2.0: C#
public sealed class OracleCommand : DbCommand, 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.
To minimize the number of open server cursors, OracleCommand objects should be
explicitly disposed.
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();
cmd.Connection = con;
cmd.CommandType = CommandType.Text;
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Members
■ OracleCommand Constructors
■ OracleCommand Static Methods
■ OracleCommand Properties
■ OracleCommand Public Methods
OracleCommand Members
OracleCommand Constructors
OracleCommand constructors are listed in Table 5–1.
OracleCommand Properties
OracleCommand properties are listed in Table 5–3.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
OracleCommand Constructors
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
OracleCommand()
This constructor instantiates a new instance of OracleCommand class.
Declaration
// C#
public OracleCommand();
Remarks
Default constructor.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
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-3
■ OracleCommand Class
■ OracleCommand Members
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
The SQL command or stored procedure to be executed.
■ OracleConnection
The connection to the Oracle database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
OracleCommand Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "LOB Support" on page 3-61 for further information on how
this property used with LOBs
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.
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();
if (cmd.AddToStatementCache)
Console.WriteLine("Added to the statement cache:" + cmd.CommandText);
else
Console.WriteLine("Not added to the statement cache:" + cmd.CommandText);
// 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();
if (cmd.AddToStatementCache)
Console.WriteLine("Added to the statement cache:" + cmd.CommandText);
else
// Clean up
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "Statement Caching" on page 3-42
■ ConnectionString on page 5-77
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.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "Array Binding" on page 3-39
■ "Value" on page 5-275
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.
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "Array Binding" on page 3-39
■ "Value" on page 5-275
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
// ADO.NET 2.0: C#
public override 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-3
■ OracleCommand Class
■ OracleCommand Members
CommandTimeout
This property specifies the number of seconds that the command is allowed to execute
before terminating with an exception.
Declaration
// ADO.NET 2.0: C#
public override int CommandTimeout {get; set;}
Property Value
int
Implements
IDbCommand.CommandTimeout
Exceptions
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. 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ http://msdn.microsoft.com/library for detailed
information about this Microsoft .NET Framework 1.1 feature
CommandType
This property specifies the command type that indicates how the CommandText
property is to be interpreted.
Declaration
// ADO.NET 2.0: C#
public override CommandType CommandType {get; 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
DesignTimeVisible
This property specifies whether or not the OracleCommand object is visible on
designer controls.
Declaration
// C#
public override bool DesignTimeVisible { get; set; }
Property Value
A value that indicate whether or not OracleCommand object is visible in a control.
The default is true.
Remarks
This property is used by developers to indicate whether or not OracleCommand
object is visible in a control.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
FetchSize
This property specifies the size of OracleDataReader's internal cache to store result
set data.
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 = 131072.
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 database round-trip.
If the XmlCommandType property is set to any value other than None, this property is
ignored.
The RowSize and FetchSize properties handle UDT and XMLType data differently
than other scalar data types. Because only a reference to the UDT and XMLType data is
stored in the ODP.NET's internal cache, the RowSize property accounts for only the
memory needed for the reference (which is very small) and not the actual size of the
UDT and XMLType data. Thus, applications can inadvertently fetch a large number of
UDT or XMLType instances from the database in a single database round-trip. This is
because the actual size of UDT and XMLType data do not count against the
FetchSize, and it would require numerous UDT and XMLType references to fill up
the default cache size of 131072 bytes. Therefore, when fetching UDT or XMLType
data, the FetchSize property must be appropriately configured to control the
number of UDT and XMLType instances that are to be fetched, rather than the amount
of the actual UDT and XMLType data to be fetched.
NOTE: For LOB and LONG data types, only the sizes specified in the
InitialLOBFetchSize and InitialLONGFetchSize properties are accounted for
by the RowSize property in addition to the metadata and reference information that is
maintained by the cache for each LOB in the select list.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ OracleDataReader "FetchSize" on page 5-159
InitialLOBFetchSize
This property specifies the amount of data that the OracleDataReader initially
fetches for LOB columns.
Declaration
// C#
public int InitialLOBFetchSize {get; set;}
Property Value
An int specifying the number of characters or bytes to fetch initially.
Exceptions
ArgumentException - The InitialLOBFetchSize value specified is invalid.
Remarks
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.
The InitialLOBFetchSize value is used to determine the length of the LOB
column data to fetch, if the LOB column is in the select list. If the select list does not
contain a LOB column, the InitialLOBFetchSize value is ignored.
When InitialLOBFetchSize is set to -1, the entire LOB data is prefetched and
stored in the fetch array. Calls to GetString, GetChars or GetBytes in
OracleDataReader allow retrieving the entire data. In this case, the following
methods are disabled.
■ GetOracleBlob
■ GetOracleClob
■ GetOracleClobForUpdate
■ GetOracleBlobForUpdate
This feature works for retrieving data from Oracle Database 9i release 2 (9.2) and later
Default = 0.
For Oracle Database 10g release 2 (10.2) and later:
The maximum value supported for InitialLOBFetchSize is 2 GB.
Prior to Oracle Database 10g release 2 (10.2), if the InitialLOBFetchSize is set to a
nonzero value, GetOracleBlob and GetOracleClob methods were disabled. BLOB
and CLOB data was fetched by using GetBytes and GetChars methods, respectively.
In Oracle Database 10g release 2 (10.2), this restriction no longer exists.
GetOracleBlob and GetOracleClob methods can be used for any
InitialLOBFetchSize value zero or greater.
For releases prior to Oracle Database 10g release 2 (10.2):
The maximum value supported for InitialLOBFetchSize is 32 K.
To fetch more than the specified InitialLOBFetchSize value, 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)
If this property is set to 0, none of the preceding is required
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "Obtaining LOB Data" on page 3-52
InitialLONGFetchSize
This property specifies the amount of data 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)
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.
When InitialLONGFetchSize is set to -1, the entire LONG or LONG RAW data is
prefetched and stored in the fetch array. Calls to GetString, GetChars, or
GetBytes in OracleDataReader allow retrieving the entire data.
Default = 0.
Setting this property to 0 defers the LONG and LONG RAW data retrieval entirely until
the application specifically requests it.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "Obtaining LONG and LONG RAW Data" on page 3-51 for
further information
Notification
This instance property indicates that there is a notification request for the command.
Declaration
// C#
public OracleNotificationRequest Notification {set; get;}
Property Value
A notification request for the command.
Remarks
When a changed notification is first registered, the client listener is started in order to
receive any database notification. The listener uses the port number defined in the
OracleDependency.Port static field. Subsequent change notification registrations
use the same listener in the same client process and do not start another listener.
When Notification is set to an OracleNotificationRequest instance, a
notification registration is created (if it has not already been created) when the
command is executed. Once the registration is created, the properties of the
OracleNotificationRequest instance cannot be modified. If the notification
registration has already been created, the result set that is associated with the
command is added to the existing registration.
When Notification is set to null, subsequent command executions do not require
a notification request. If a notification request is not required, set the Notification
property to null, or set the NotificationAutoEnlist property to false.
For Continuous Query Notification, a notification request can be used for multiple
command executions. In that case, any query result set associated with different
commands can be invalidated within the same registration.
When the OracleDependency.OnChange event is fired, if the ROWID column is
explicitly included in the query (or AddRowid property is set to true), then the
Rowid column contains ROWID values in the DataTable referenced by the
OracleNotificationEventArgs.Details property. This behavior can be
overridden by explicitly requesting for an inclusion and exclusion of ROWID values in
the OracleNotificationEventArgs by setting the
OracleDependency.RowidInfo to OracleRowidInfo.Include or
OracleRowidInfo.Exclude, respectively.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "Database Change Notification Support" on page 3-97
■ Chapter 9, "Database Change Notification" on page 9-1
NotificationAutoEnlist
This instance property indicates whether or not to register for a database change
notification with the database automatically when the command is executed.
Declaration
// C#
public bool NotificationAutoEnlist {set; get;}
Property Value
A bool value indicating whether or not to make a database change notification
request automatically, when the command is executed. If
NotificationAutoEnlist is set to true, and the Notification property is set
appropriately, a database change notification request is registered automatically;
otherwise, no database change notification registration is made.
Default value: true
Remarks
A notification request can be used for multiple command executions using the same
OracleCommand instance. In that case, set the NotificationAutoEnlist property
to true.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "Database Change Notification Support" on page 3-97
■ Chapter 9, "Database Change Notification" on page 9-1
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
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;}
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 database round-trip, the
OracleDataReader 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().
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ OracleDataReader "FetchSize" on page 5-17
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-3
■ OracleCommand Class
■ OracleCommand Members
UpdatedRowSource
This property specifies how query command results are applied to the row to be
updated.
Declaration
// ADO.NET 2.0: C#
public override UpdateRowSource UpdatedRowSource {get; set;}
Property Value
An UpdateRowSource.
Implements
IDbCommand
Exceptions
ArgumentException - The UpdateRowSource value specified is invalid.
Remarks
Always returns UpdateRowSource,
Set accessor throws an ArgumentException if the value is other than
UpdateRowSource.None.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
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-3
■ OracleCommand Class
■ OracleCommand Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
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.
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-3
■ OracleCommand Class
■ OracleCommand Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
Cancel
This method attempts to cancel a command that is currently executing on a particular
connection.
Declaration
// ADO.NET 2.0: C#
public override void Cancel();
Implements
IDbCommand.Cancel
Remarks
If cancellation of the command succeeds, an exception is thrown. If 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. Invoking the Cancel method does
not guarantee that the command executing at the time will always be cancelled. The
execution may complete before it can be terminated. In such cases, no exception is
thrown.
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
simultaneously, issuing a Cancel method invocation may cancel any of the issued
commands. This is because the command designated for cancellation may complete
before the Cancel invocation is effective. If this happens, a command executed by a
different OracleCommand could be cancelled instead.
There are several ways to avoid this non-deterministic situation that the Cancel
method can cause:
■ The application can create just one OracleCommand object for each connection.
Doing so assures that the Cancel invocation only cancels commands executed by
the OracleCommand object using a particular connection.
■ Command executions in the application are synchronized between
OracleCommand objects that use the same connection.
These suggestions do not apply if Cancel is not used in the application.
Because 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, 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#
using System;
using System.Data;
using Oracle.DataAccess.Client;
using System.Threading;
class CancelSample
{
private OracleCommand cmd;
Thread t1, t2;
// threads signal following events when assigned operations are completed
// 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;
}
cmd.Cancel();
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
Console.WriteLine("Cancel done.");
Console.WriteLine("CancelEvent.Set()");
CancelEvent.Set();
}
ExecutionCompleteEvents[0] = test1.FinishedEvent;
ExecutionCompleteEvents[1] = test2.FinishedEvent;
ExecutionCompleteEvents[2] = test3.FinishedEvent;
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ http://msdn.microsoft.com/library for detailed
information about this Microsoft .NET Framework 1.1 feature
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
CreateParameter
This method creates a new instance of OracleParameter class.
Declaration
// C#
public OracleParameter CreateParameter();
Return Value
A new OracleParameter with default values.
Implements
IDbCommand
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
ExecuteNonQuery
This method executes a SQL statement or a command using the XmlCommandType
and CommandText properties and returns the number of rows affected.
Declaration
// ADO.NET 2.0: C#
public override 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.
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();
// 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 later, to be installed in the database. Oracle XDK can be downloaded from Oracle
Technology Network (OTN).
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ http://otn.oracle.com/
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
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 specified command executes this stored procedure when ExecuteReader is
called. If parameters for the stored procedure consist of REF CURSOR objects, behavior
differs depending on whether ExecuteReader() or ExecuteNonQuery() is called.
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();
while (reader.Read())
{
Console.WriteLine("Employee Name : " + reader.GetString(0));
}
// Clean up
reader.Dispose();
cmd.Dispose();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "OracleRefCursor Class" on page 13-113
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
The 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 command 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 13-113.
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-51.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ "OracleRefCursor Class" on page 13-113
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
// ADO.NET 2.0: C#
public override object ExecuteScalar();
Return Value
An object which represents the value of the first row, first column.
Implements
IDbCommand
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();
// Clean up
cmd.Dispose();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
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();
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ Oracle XML DB Developer's Guide
■ http://otn.oracle.com/
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.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ Oracle XML DB Developer's Guide
■ http://otn.oracle.com/
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
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommand Class
■ OracleCommand Members
■ Oracle XML DB Developer's Guide
■ http://otn.oracle.com/
OracleCommandBuilder Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.ComponentModel.Component
System.Data.Common.DbCommandBuilder (ADO.NET 2.0 only)
OracleDataAccess.Client.OracleCommandBuilder
Declaration
// ADO.NET 2.0: C#
public sealed class OracleCommandBuilder : DbCommandBuilder
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()
{
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
string cmdstr = "SELECT empno, sal from emp";
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Members
■ OracleCommandBuilder Constructors
■ OracleCommandBuilder Static Methods
■ OracleCommandBuilder Properties
■ OracleCommandBuilder Public Methods
■ OracleCommandBuilder Events
OracleCommandBuilder Members
OracleCommandBuilder Constructors
OracleCommandBuilder constructors are listed in Table 5–8.
OracleCommandBuilder Properties
OracleCommandBuilder properties are listed in Table 5–10.
OracleCommandBuilder Events
The OracleCommandBuilder event is listed in Table 5–12.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
OracleCommandBuilder Constructors
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
OracleCommandBuilder()
This constructor creates an instance of the OracleCommandBuilder class.
Declaration
// C#
public OracleCommandBuilder();
Remarks
Default constructor.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
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-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
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
When DeriveParameters is used to populate the Parameter collection of an
OracleCommand Object that represents a stored function, the return value of the
function is bound as the first parameter (at position 0 of the
OracleParameterCollection).
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 database round-trip and should only be used during
design time. To avoid unnecessary database 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
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\"";
// C#
using System;
using System.Data;
using Oracle.DataAccess.Client;
class DeriveParametersSample
{
static void Main()
{
// Create an OracleCommand
OracleCommand cmd = new OracleCommand("MyOracleStoredProc", con);
cmd.CommandType = CommandType.StoredProcedure;
// Derive Parameters
OracleCommandBuilder.DeriveParameters(cmd);
Console.WriteLine("Parameters Derived");
con.Close();
con.Dispose();
}
}
Example
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ 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 Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
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.
Remarks
Default = false
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
CatalogLocation
This property is not supported.
Declaration
// ADO.NET 2.0: C#
public override CatalogLocation CatalogLocation {get; set;}
Exceptions
NotSupportedException - This property is not supported.
Remarks
This property is not supported.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
CatalogSeparator
This property is not supported.
Declaration
// ADO.NET 2.0: C#
public override string CatalogSeparator {get; set;}
Exceptions
NotSupportedException - This property is not supported.
Remarks
This property is not supported.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
ConflictOption
This property is not supported.
Declaration
// ADO.NET 2.0: C#
public override string ConflictOption {get; set;}
Exceptions
NotSupportedException - This property is not supported.
Remarks
This property is not supported.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
DataAdapter
This property indicates the OracleDataAdapter object for which the SQL
statements are generated.
Declaration
// C#
OracleDataAdapter DataAdapter{get; set;}
Property Value
An OracleDataAdapter object.
Remarks
Default = null
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
QuotePrefix
This property specifies the beginning character or characters used to specify database
objects whose names contain special characters such as spaces or reserved words.
Declaration
// ADO.NET 2.0: C#
public override string QuotePrefix {get; set;}
Property Value
The beginning character or characters to use. The default value is "\"".
Remarks
This property is independent of any OracleConnection or OracleCommand
objects.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
QuoteSuffix
This property specifies the ending character or characters used to specify database
objects whose names contain special characters such as spaces or reserved words.
Declaration
// ADO.NET 2.0: C#
public override string QuoteSuffix {get; set;}
Property Value
The ending character or characters to use. The default value is "\"".
Remarks
This property is independent of any OracleConnection or OracleCommand
objects.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
SchemaSeparator
This property specifies the character to be used for the separator between the schema
identifier and other identifiers.
Declaration
// ADO.NET 2.0: C#
public override string SchemaSeparator {get; set; }
Property Value
The character to be used as the schema separator.
Exceptions
NotSupportedException - The input value is not a dot (.).
Remarks
The default schema separator is a dot (.). The only acceptable value for this property
is a dot (.).
Example
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class SchemaSeperatorSample
{
static void Main(string[] args)
{
try
{
OracleCommandBuilder cmdBuilder = new OracleCommandBuilder();
//schemaSeparator is dot(.)
Console.WriteLine("schemaSeparator is {0}",
cmdBuilder.SchemaSeparator);
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
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.
InvalidOperationException - Either the SelectCommand or the DataAdapter
property is null, or the primary key cannot be retrieved from the SelectCommand
property of the OracleDataAdapter.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
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.
InvalidOperationException - Either the SelectCommand or the DataAdapter
property is null, or the primary key cannot be retrieved from the SelectCommand
property of the OracleDataAdapter.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
QuoteIdentifier
This method returns the correct quoted form of the provided unquoted identifier, with
any embedded quotes in the identifier properly escaped.
Declaration
// ADO.NET 2.0: C#
public override string QuoteIdentifier(string unquotedIdentifier);
Parameters
■ UnquotedIdentifier
An unquoted identifier string.
Return Value
The quoted version of the identifier. Embedded quotes within the identifier are
properly escaped.
Exceptions
ArgumentNullException - The input parameter is null.
Remarks
This method is independent of any OracleConnection or OracleCommand objects.
Example
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class QuoteIdentifierSample
{
static void Main(string[] args)
{
OracleCommandBuilder builder = new OracleCommandBuilder();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
RefreshSchema
This method refreshes the database schema information used to generate INSERT,
UPDATE, or DELETE statements.
Declaration
// ADO.NET 2.0: C#
public override void RefreshSchema();
Remarks
An application should call RefreshSchema whenever the SelectCommand value of
the OracleDataAdapter object changes.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
UnquoteIdentifier
This method returns the correct unquoted form of the provided quoted identifier,
removing any escape notation for quotes embedded in the identifier.
Declaration
// ADO.NET 2.0: C#
public override string UnquoteIdentifier(string quotedIdentifier);
Parameters
■ quotedIdentifier
The quoted string identifier.
Return Value
The unquoted identifier, with escape notation for any embedded quotes removed.
Exceptions
ArgumentNullException - The input parameter is null.
ArgumentException - The input parameter is empty.
Remarks
This method is independent of any OracleConnection or OracleCommand objects.
Example
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class UnQuoteIdentifierSample
{
static void Main(string[] args)
{
//create an OracleCommandBuilder object.
OracleCommandBuilder builder = new OracleCommandBuilder();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
OracleCommandBuilder Events
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleCommandBuilder Class
■ OracleCommandBuilder Members
OracleConnection Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.ComponentModel.Component
System.Data.Common.DbConnection (ADO.NET 2.0 only)
Oracle.DataAccess.Client.OracleConnection
Declaration
// ADO.NET 2.0: C#
public sealed class OracleConnection : DbConnection, 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();
// Clean up
reader.Dispose();
cmd.Dispose();
con.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Members
■ OracleConnection Constructors
■ OracleConnection Static Properties
■ OracleConnection Static Methods
■ OracleConnection Properties
■ OracleConnection Public Methods
■ OracleConnection Events
OracleConnection Members
OracleConnection Constructors
OracleConnection constructors are listed in Table 5–17.
OracleConnection Properties
OracleConnection properties are listed in Table 5–20.
OracleConnection Events
OracleConnection events are listed in Table 5–22.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
OracleConnection Constructors
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
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 (default value of 0 is used for the implicit database
connection)
■ DataSource = empty string
■ ServerVersion = empty string
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
OracleConnection(String)
This constructor instantiates a new instance of the OracleConnection class with the
provided connection string.
Declaration
// C#
public OracleConnection(String connectionString);
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 (default value of 0 is used for the implicit database
connection)
■ DataSource = empty string
■ ServerVersion = empty string
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
IsAvailable
This property indicates whether or the implicit database connection is available for
use.
Declaration
// C#
public static bool IsAvailable {get;}
Property Value
Returns true if the implicit database connection is available for use.
Remarks
The availability of the implicit database connection can be checked at run time through
this static property. When Oracle Data Provider for .NET is used within a .NET stored
procedure, this property always returns true. Otherwise, false is returned.
To obtain an OracleConnection object in a .NET stored procedure that represents
the implicit database connection, set the ConnectionString property of the
OracleConnection object to "context connection=true" and invoke the Open
method.
Note that not all features that are available for an explicit user connection are available
for an implicit database connection. See "Implicit Database Connection" on page 4-2
for details.
Example
// C# (Library/DLL)
using System;
using Oracle.DataAccess.Client;
con.Open();
Console.WriteLine("connected!");
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
ClearPool
This method clears the connection pool that is associated with the provided
OracleConnection object.
Declaration
// C#
public static void ClearPool(OracleConnection connection);
Remarks
When this method is invoked, all idle connections are closed and freed from the pool.
Currently used connections are not discarded until they are returned to the pool.
The ClearPool method should be invoked only when valid connections can be
created (that is, the database is up and can be connected to). Otherwise, the
ClearPool method may just create invalid connections to a downed database
instance. Assuming valid database connections, a ClearPool invocation creates a
connection pool with usable connections. Therefore, connection requests succeed even
after the invocation of this method. Connections created after this method invocation
are not cleared unless another invocation is made.
This method can be invoked with an OracleConnection object before opening the
connection as well as after, provided the ConnectionString is properly set.
Exceptions
InvalidOperationException – Either the connection pool cannot be found or the
provided connection string is invalid.
Example
// C#
// Sample demonstrating the use of ClearPool API in OracleConnection class
using System;
using Oracle.DataAccess.Client;
class ClearPoolSample
{
static void Main()
{
Console.WriteLine("Running ClearPool sample..." );
// Set the connection string
string strConn = "User Id=scott;Password=tiger;Data Source=oracle;" +
"Min pool size=5;";
OracleConnection conn = new OracleConnection(strConn);
// cleanup
conn.Close();
Console.WriteLine("Done!");
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
ClearAllPools
This method clears all connections from all the connection pools.
Declaration
// C#
public static void ClearAllPools();
Remarks
This call is analogous to calling ClearPool for all the connection pools that are
created for the application.
Exceptions
InvalidOperationException – No connection pool could be found for the
application.
Example
// C#
// Sample demonstrating the use of ClearAllPools API in OracleConnection class
using System;
using Oracle.DataAccess.Client;
class ClearAllPoolsSample
{
static void Main()
{
Console.WriteLine("Running ClearAllPools sample..." );
// Set the connection string
string strConn = "User Id=scott;Password=tiger;Data Source=oracle;" +
"Min pool size=5;";
OracleConnection conn = new OracleConnection(strConn);
// Open the connections. Separate pools are created for conn and connNew
conn.Open();
connNew.Open();
// cleanup
conn.Close();
connNew.Close();
Console.WriteLine("Done!");
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "ClearPool" on page 5-73
OracleConnection Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
ActionName
This property specifies the action name for the connection.
Declaration
// C#
public string ActionName {set;}
Property Value
The string to be used as the action name.
Remarks
The default value is null and the maximum length of the string is 32 bytes.
Using the ActionName property allows the application to set the action name in the
application context for a given OracleConnection object.
The ActionName property is reset to null when the Close or Dispose method is
called on the OracleConnection object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "Client Identifier and End-to-End Tracing" on page 3-16
■ Oracle Database Security Guide
ClientId
This property specifies the client identifier for the connection.
Declaration
// C#
public string ClientId {set;}
Property Value
The string to be used as the client identifier.
Remarks
The default value is null and the maximum length is 64 bytes.
Using the ClientId property allows the application to set the client identifier in the
application context for every database session using ODP.NET. This enables ODP.NET
developers to configure the Oracle Virtual Private Database (VPD) more easily.
Setting ClientId to null resets the client identifier for the connection. Setting
ClientId to an empty string sets the client identifier for the connection to an empty
string. ClientId is set to null when the Close method is called on the
OracleConnection object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "Client Identifier and End-to-End Tracing" on page 3-16
■ Oracle Database Security Guide
ConnectionString
This property specifies connection information used to connect to an Oracle database.
Declaration
// ADO.NET 2.0: C#
public override 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:
"User Id=scott;password=tiger;data source=oracle"
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
ConnectionTimeout
This property indicates the maximum amount of time that the Open method can take
to obtain a pooled connection before the request is terminated.
Declaration
// ADO.NET 2.0: C#
public override int ConnectionTimeout {get;}
Property Value
The maximum time allowed for a pooled connection request, in seconds.
Implements
IDbConnection
Remarks
This property indicates the connection timeout that has been set using the
ConnectionString attribute Connection TimeOut.
This property is read-only.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
Database
This property is not supported.
Declaration
// ADO.NET 2.0: C#
public override string Database {get;}
Property Value
A string.
Implements
IDbConnection.Database
Remarks
This property is not supported. It always returns an empty string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
DatabaseDomainName
This property specifies the name of the database domain that this connection is
connected to.
Declaration
// C#
public string DatabaseDomainName {get;}
Property Value
The database domain that this connection is connected to.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
DatabaseName
This property specifies the name of the database that this connection is connected to.
Declaration
// C#
public string DatabaseName {get;}
Property Value
The database that this connection is connected to.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
DataSource
This property specifies the Oracle Net Services Name, Connect Descriptor, or an easy
connect naming that identifies the database to which to connect
Declaration
// ADO.NET 2.0: C#
public override string DataSource {get;}
Property Value
Oracle Net Services Name, Connect Descriptor, or an easy connect naming that
identifies the database to which to connect.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
HostName
This property specifies the name of the host that this connection is connected to.
Declaration
// C#
public string HostName {get;}
Property Value
The host that this connection is connected to.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
InstanceName
This property specifies the name of the instance that this connection is connected to.
Declaration
// C#
public string InstanceName {get;}
Property Value
The instance that this connection is connected to.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
ModuleName
This property specifies the module name for the connection.
Declaration
// C#
public string ModuleName {set;}
Property Value
The string to be used as the module name.
Remarks
The default value is null and the maximum string length is 48 bytes.
Using the ModuleName property allows the application to set the module name in the
application context for a given OracleConnection object.
The ModuleName property is reset to null when the Close or Dispose method is
called on the OracleConnection object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "Client Identifier and End-to-End Tracing" on page 3-16
■ Oracle Database Security Guide
ServerVersion
This property specifies the version number of the Oracle database to which the
OracleConnection has established a connection.
Declaration
// ADO.NET 2.0: C#
public override string ServerVersion {get;}
Property Value
The version of the Oracle database.
Exceptions
InvalidOperationException - The connection is closed.
Remarks
The default is an empty string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
ServiceName
This property specifies the name of the service that this connection is connected to.
Declaration
// C#
public string ServiceName {get;}
Property Value
The service that this connection is connected to.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
State
This property specifies the current state of the connection.
Declaration
// ADO.NET 2.0: C#
public override 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-3
■ OracleConnection Class
■ OracleConnection Members
StatementCacheSize
This property specifies the current size of the statement cache associated with this
connection.
Declaration
// C#
public int StatementCacheSize{get;}
Property Value
An integer value indicating the size of the statement cache.
Remarks
If self tuning is not enabled, then the default value of this property depends upon the
statement cache size specified in the connection string, application configuration file,
or the registry. If none of these values are specified, then a default value of 0 is used.
If self tuning is enabled, then the property value is adjusted automatically. Any values
specified in the connection string, application configuration file, or the registry are
ignored.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
BeginTransaction
BeginTransaction methods begin local transactions.
Overload List
■ BeginTransaction()
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
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
Exceptions
InvalidOperationException - A transaction has already been started.
ArgumentException - The isolationLevel specified is invalid.
Remarks
The following isolation levels are supported: IsolationLevel.ReadCommitted
and 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();
// Start a transaction
OracleTransaction txn = con.BeginTransaction(IsolationLevel.ReadCommitted);
// Rollback transaction
txn.Rollback();
Console.WriteLine("Transaction rolledback");
// Clean up
txn.Dispose();
cmd.Dispose();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
ChangeDatabase
This method is not supported.
Declaration
// ADO.NET 2.0: C#
public override void ChangeDatabase(string databaseName);
Parameters
■ databaseName
The name of the database that replaces the current database name.
Implements
IDbConnection.ChangeDatabase
Exceptions
NotSupportedException - Method not supported.
Remarks
This method is not supported and throws a NotSupportedException if invoked.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
Clone
This method creates a copy of an OracleConnection object.
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();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
Close
This method closes the connection to the database.
Declaration
// ADO.NET 2.0: C#
public override void Close();
Implements
IDbConnection
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().
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
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();
// Clean up
reader.Dispose();
cmd.Dispose();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
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.
Exceptions
InvalidOperationException - The connection is part of a local transaction or the
connection is closed.
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.
Example
Application:
// C#
using System;
using System.EnterpriseServices;
using DistribTxnSample;
class DistribTxnSample_App
{
static void Main()
{
DistribTxnSample_Comp comp = new DistribTxnSample_Comp();
comp.DoWork();
}
}
Component:
// C#
using System;
using System.Data;
using Oracle.DataAccess.Client;
using System.EnterpriseServices;
namespace DistribTxnSample
{
[Transaction(TransactionOption.RequiresNew)]
public class DistribTxnSample_Comp : ServicedComponent
{
public void DoWork()
{
string constr =
"User Id=scott;Password=tiger;Data Source=oracle;enlist=false";
OracleConnection con = new OracleConnection(constr);
con.Open();
// Commit
ContextUtil.SetComplete();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "EnlistTransaction" on page 5-97
■ http://msdn.microsoft.com/library for detailed
information about this Microsoft .NET Framework 1.1 feature
EnlistTransaction
This method enlists the connection to the specified transaction.
Supported Only in ADO.NET 2.0-Compliant ODP.NET
Declaration
// C#
public override void EnlistTransaction(Transaction transaction)
Parameters
■ transaction
A System.Transactions.Transaction object.
Exceptions
InvalidOperationException - The connection is part of a local transaction or the
connection is closed.
Remarks
Invocation of this method immediately enlists the connection to a transaction that is
specified by the provided transaction parameter.
If OracleConnection is still associated with a distributed transaction that has not
completed from a previous EnlistTransaction method invocation, calling this
method will cause an exception to be thrown.
In general, for transaction enlistments to succeed, the "enlist" connection string
attribute must be set to either "true" or "dynamic" before invoking the Open
method. Setting the "enlist" connection string attribute to "true" will implicitly
enlist the connection when the Open method is called, if the connection is within a
transaction context. Setting it to "dynamic" allows the connection to dynamically
enlist in transactions when an EnlistTransaction or
EnlistDistributedTransaction method is called. The "enlist" attribute
should be set to "false" only if the connection will never enlist in a transaction.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "System.Transactions and Promotable Transactions" on
page 3-22
■ "EnlistDistributedTransaction" on page 5-95
FlushCache
This method flushes all updates and deletes made through REF objects retrieved using
this connection.
Declaration
// c#
public void FlushCache();
Exceptions
InvalidOperationException - The specified connection is not open.
Remarks
Before flushing objects, it is required that the application has explicitly started a
transaction by executing the BeginTransaction method on the
OracleConnection object. This is because if the object being flushed has not already
been locked by the application, an exclusive lock is obtained implicitly for the object.
The lock is only released when the transaction commits or rollbacks.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
GetSchema
GetSchema methods return schema information for the data source of the
OracleConnection.
Supported Only in ADO.NET 2.0-Compliant ODP.NET
Overload List
■ GetSchema()
This method returns schema information for the data source of the
OracleConnection.
■ GetSchema (string collectionName)
This method returns schema information for the data source of the
OracleConnection using the specified string for the collection name.
■ GetSchema (string collectionName, string[] restrictions)
This method returns schema information for the data source of the
OracleConnection using the specified string for the collection name and the
specified string array for the restriction values.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
GetSchema()
This method returns schema information for the data source of the
OracleConnection.
Declaration
// ADO.NET 2.0: C#
public override DataTable GetSchema();
Return Value
A DataTable object.
Exceptions
InvalidOperationException – The connection is closed.
Remarks
This method returns a DataTable object that contains a row for each metadata
collection available from the database.
The method is equivalent to specifying the String value "MetaDataCollections"
when using the GetSchema(String) method.
Example
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class GetSchemaSample
{
static void Main(string[] args)
{
string constr = "User Id=scott; Password=tiger; Data Source=oracle;";
string ProviderName = "Oracle.DataAccess.Client";
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
Declaration
// ADO.NET 2.0: C#
public override DataTable GetSchema (string collectionName);
Parameters
collectionName
Name of the collection for which metadata is required.
Return Value
A DataTable object.
Exceptions
ArgumentException – The requested collection is not defined.
InvalidOperationException – The connection is closed.
InvalidOperationException – The requested collection is not supported by
current version of Oracle database.
InvalidOperationException – No population string is specified for requested
collection.
Example
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class GetSchemaSample
{
static void Main(string[] args)
{
string constr = "User Id=scott; Password=tiger; Data Source=oracle;";
string ProviderName = "Oracle.DataAccess.Client";
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
Declaration
// ADO.NET 2.0: C#
public override DataTable GetSchema (string collectionName,
string[] restrictions);
Parameters
■ collectionName
The name of the collection of metadata being retrieved.
■ restrictions
An array of restrictions that apply to the metadata being retrieved.
Return Value
A DataTable object.
Exception
■ ArgumentException – The requested collection is not defined.
■ InvalidOperationException – One of the following conditions exist:
– The connection is closed.
Remarks
This method takes the name of a metadata collection and an array of String values that
specify the restrictions for filtering the rows in the returned DataTable. This returns a
DataTable that contains only rows from the specified metadata collection that match
the specified restrictions.
For example, if the Columns collection has three restrictions (owner, tablename, and
columnname), to retrieve all the columns for the EMP table regardless of schema, the
GetSchema method must pass in at least these values: null, EMP.
If no restriction value is passed in, default values are used for that restriction, which is
the same as passing in null. This differs from passing in an empty string for the
parameter value. In this case, the empty string ("") is considered the value for the
specified parameter.
collectionName is not case-sensitive, but restrictions (string values) are.
Example
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class GetSchemaSample
{
static void Main(string[] args)
{
string constr = "User Id=scott; Password=tiger; Data Source=oracle;";
string ProviderName = "Oracle.DataAccess.Client";
//Get Restrictions
DataTable dtRestrictions =
conn.GetSchema(DbMetaDataCollectionNames.Restrictions);
DataView dv = dtRestrictions.DefaultView;
dtRestrictions.Rows[i]["RestrictionDefault"]);
// clear collection
for (int i = 0; i < 3; i++)
restrictions[i] = null;
//Get all columns from all tables named "EMP" owned by any
//owner/schema
restrictions[1] = "EMP";
DataTable dtAllEmpCols = conn.GetSchema("Columns", restrictions);
// clear collection
for (int i = 0; i < 3; i++)
restrictions[i] = null;
// clear collection
for (int i = 0; i < 3; i++)
restrictions[i] = null;
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
GetSessionInfo
GetSessionInfo returns or refreshes an OracleGlobalization object that
represents the globalization settings of the session.
Overload List:
■ GetSessionInfo()
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
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();
// Clean up
cmd.Dispose();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
Open
This method opens a connection to an Oracle database.
Declaration
// ADO.NET 2.0: C#
public overide void Open();
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "Password Expiration" on page 3-12
PurgeStatementCache
This method flushes the statement cache by closing all open cursors on the database,
when statement caching is enabled.
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.
Invocation of this method purges the cached cursors that are associated with the
OracleConnection. It does not purge all the cached cursors in the database.
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();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "Statement Caching" on page 3-42
■ ConnectionString on page 5-77
SetSessionInfo
This method alters the session's globalization settings with all the property values
specified in the provided OracleGlobalization object.
Declaration
// C#
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();
// Clean up
cmd.Dispose();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
OracleConnection Events
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
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.
Remarks
The Failover event is raised when a connection to an Oracle instance is
unexpectedly severed. The client should create an OracleFailoverEventHandler
delegate to listen to this event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "OracleFailoverEventArgs Properties" on page 11-7
■ "OracleFailoverEventHandler Delegate" on page 11-9
HAEvent
This event is triggered when an HA event occurs.
Declaration
// C#
public static event OracleHAEventHandler HAEvent;
Event Data
The event handler receives an OracleHAEventArgs object which exposes the
following properties containing information about the event.
■ Source
Indicates the source of the event.
■ Status
Indicates the status of the event.
■ DatabaseName
Indicates the database name affected by this event.
■ DatabaseDomainName
Indicates the database domain name affected by this event.
■ HostName
Indicates the host name affected by this event.
■ InstanceName
Indicates the instance name affected by this event.
■ ServiceName
Indicates the service name affected by this event.
■ Time
Indicates the time of the event.
Remarks
The HAEvent is static, which means that any HA Events that happen within the
application domain can trigger this event. Note that in order to receive HA event
notifications, OracleConnection objects that establish connections within the
application domain must have "ha events=true" in the application. Otherwise, the
application never receives any HA Events.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "OracleHAEventArgs Properties" on page 8-4
■ "OracleHAEventHandler Delegate" on page 8-8
InfoMessage
This event is triggered for any message or warning sent by the database.
Declaration
// C#
public event OracleInfoMessageEventHandler InfoMessage;
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnection Class
■ OracleConnection Members
■ "OracleInfoMessageEventArgs Properties" on page 5-242
■ "OracleInfoMessageEventHandler Delegate" on page 5-245
StateChange
This event is triggered when the connection state changes.
Declaration
// ADO.NET 2.0: C#
public override 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-3
■ OracleConnection Class
■ OracleConnection Members
■ Microsoft ADO.NET documentation for a description of
StateChangeEventHandler
OracleDataAdapter Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.ComponentModel.Component
System.Data.Common.DataAdapter
System.Data.Common.DbDataAdapter (ADO.NET 2.0 only)
Oracle.DataAccess.Client.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";
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Members
■ OracleDataAdapter Constructors
■ OracleDataAdapter Static Methods
■ OracleDataAdapter Properties
■ OracleDataAdapter Public Methods
■ OracleDataAdapter Events
OracleDataAdapter Members
OracleDataAdapter Constructors
OracleDataAdapter constructors are listed in Table 5–29.
OracleDataAdapter Properties
OracleDataAdapter properties are listed in Table 5–31.
OracleDataAdapter Events
OracleDataAdapter events are listed in Table 5–33.
OracleDataAdapter Constructors
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
OracleDataAdapter(OracleCommand)
This constructor creates an instance of an OracleDataAdapter class with the
provided OracleCommand as the SelectCommand.
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
OracleDataAdapter Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
Requery
This property determines whether or not 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-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleDataAdapter Requery Property" on page 3-108
ReturnProviderSpecificTypes
This property determines if the Fill method returns ODP.NET-specific values or
.NET common language specification compliant values.
Supported Only in ADO.NET 2.0-Compliant ODP.NET
Declaration
// C#
public Boolean ReturnProviderSpecificTypes {get; set;}
Property Value
A value that indicates whether or not the Fill method returns ODP.NET-specific
values.
A value of false indicates that the Fill method returns .NET common language
specification compliant values.
The default is false.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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 hash table.
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
See the example in "OracleDataAdapter Safe Type Mapping" on page 3-104.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleDataAdapter Safe Type Mapping" on page 3-104
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.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleDataAdapter Requery Property" on page 3-108
UpdateBatchSize
This property specifies a value that enables or disables batch processing support, and
specifies the number of SQL statements that can be executed in a single round-trip to
the database.
Supported Only in ADO.NET 2.0-Compliant ODP.NET
Declaration
// C#
public virtual int UpdateBatchSize {get; set;}
Property Value
An integer that returns the batch size.
Exceptions
ArgumentOutOfRangeException - The value is set to a number < 0.
Remarks
Update batches executed with large amounts of data may encounter an
"PLS-00123: Program too large" error. To avoid this error, reduce the size of
UpdateBatchSize to a smaller value.
For each row in the DataSet that has been modified, added, or deleted, one SQL
statement will be executed on the database.
Values are as follows:
■ Value = 0
The data adapter executes all the SQL statements in a single database round-trip
■ Value = 1 - Default value
This value disables batch updating and SQL statements are executed one at a time.
■ Value = n where n > 1
The data adapter updates n rows of data per database round-trip.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "Batch Processing Support" on page 3-27
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-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleDataAdapter Requery Property" on page 3-108
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleDataAdapter Requery Property" on page 3-108
Fill(DataSet, OracleRefCursor)
This method adds or refreshes rows in the DataSet to match those in the provided
OracleRefCursor object.
Declaration
// C#
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleDataAdapter Requery Property" on page 3-108
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
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleDataAdapter Requery Property" on page 3-108
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.
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-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleDataAdapter Requery Property" on page 3-108
OracleDataAdapter Events
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
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.
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);
}
// 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);
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleRowUpdatedEventHandler Delegate" on page 5-330
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.
Example
The example for the RowUpdated event also shows how to use the RowUpdating
event. See RowUpdated event "Example" on page 5-135.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataAdapter Class
■ OracleDataAdapter Members
■ "OracleRowUpdatingEventHandler Delegate" on page 5-338
OracleDatabase Class
Class Inheritance
System.Object
Oracle.DataAccess.Client.OracleDatabase
Declaration
// C#
public sealed class OracleDatabase : IDisposable
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;
namespace Startup
{
class Test
{
static void Main()
{
OracleConnection con = null;
OracleDatabase db = null;
string constring = "dba privilege=sysdba;user id=scott;password=tiger;data
source=oracle";
try
{
// Open a connection to see if the DB is up
con = new OracleConnection(constring);
con.Open();
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Members
■ OracleDatabase Constructor
■ OracleDatabase Properties
■ OracleDatabase Public Methods
OracleDatabase Members
OracleDatabase Constructors
The OracleDatabase constructor is listed in Table 5–38.
OracleDatabase Properties
The OracleDatabase properties are listed in Table 5–39.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
OracleDatabase Constructor
Declaration
// C#
public OracleDatabase(String connetionString);
Parameters
■ connectionString
The connection information used to connect to the Oracle Database instance.
Remarks
The connectionString follows the same format used by the OracleConnection
object. However, the OracleDatabase constructor accepts only the user id,
password, data source, and dba privilege connection string attributes. All
other attribute values are ignored. The supplied connectionString must contain
the dba privilege connection string attribute that is set to either SYSDBA or
SYSOPER.
The OracleDatabase object creates a connection upon construction and remains
connected throughout its lifetime. The connection is destroyed when the
OracleDatabase object is disposed. This connection is not pooled to be used by another
OracleDatabase object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
OracleDatabase Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
ServerVersion
This property returns the database version number of the Oracle Database instance to
which the connection is made.
Declaration
Public string ServerVersion {get;}
Property value
Returns the database version of the Oracle Database instance.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
ExecuteNonQuery
This method executes the supplied non-SELECT statement against the database.
Declaration
// C#
public void ExecuteNonQuery(string sql);
Exceptions
OracleException - The command execution has failed.
Remarks
This method is meant for execution of DDL statements such as ALTER DATABASE
statements to OPEN and MOUNT the database, for example. This method should not be
used to execute SQL SELECT statements. This method does not support any
parameter binding.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
Shutdown
Shutdown methods shut down a database instance.
Overload List
■ Shutdown()
This method shuts down the database.
■ Shutdown(OracleDBShutdownMode, bool)
This method shuts down the database using the specified mode.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
■ "OracleDBShutdownMode Enumeration" on page 5-355
Shutdown()
This method shuts down the database.
Declaration
// C#
public void Shutdown();
Exceptions
OracleException - The database shutdown request has failed.
Remarks
This method shuts down a database instance in the
OracleDBShutdownMode.Default mode. New connections are refused, and the
method waits for the existing connections to end.
After the connections have closed, the method closes the database, dismounts the
database, and shuts down the instance using the OracleDBShutdownMode.Final
mode.
This method does not throw exceptions for cases where the database has been already
closed, dismounted, or shutdown appropriately. If other errors are encountered, then
an exception is thrown.
Invoking this method against an Oracle Real Application Clusters (RAC) database
shuts down only that database instance to which the OracleDatabase object is
connected.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
■ "OracleDBShutdownMode Enumeration" on page 5-355
Shutdown(OracleDBShutdownMode, bool)
This method shuts down the database instance using the specified mode.
Declaration
//C#
Parameters
■ shutdownMode
A OracleDBShutdownMode enumeration value.
■ bCloseDismountAndFinalize
A boolean signifying whether the database is to be closed, dismounted, and
finalized.
Exceptions
OracleException - The database shutdown request has failed.
Remarks
This method shuts down a database instance in the specified mode. If the
bCloseDismountAndFinalize parameter is true, then the method also closes the
database, dismounts the database, and shuts down the instance using the
OracleDBShutdownMode.Final mode.
If the bCloseDismountAndFinalize parameter is true, then this method does not
throw exceptions for cases where the database has been already closed, dismounted,
or shutdown appropriately. If other errors are encountered, then an exception is
thrown.
If the bCloseDismountAndFinalize parameter is false, then the application
needs to explicitly close and dismount the database. The application can then reinvoke
the method using the OracleDBShutdownMode.Final mode to properly shut down
the database. For example, if db is an instance of the OracleDatabase class, then the
application invokes the following:
1. db.Shutdown(OracleDBShutdownMode.Default, false);
2. db.ExecuteNonQuery("ALTER DATABASE CLOSE NORMAL");
3. db.ExecuteNonQuery("ALTER DTABASE DISMOUNT");
4. db.Shutdown(OracleDBShutdownMode.Final);
Note:
■ The OracleDBShutdownMode.Final enumeration value
should not be used as the shutdownMode for the initial method
invocation. The OracleDBShutdownMode.Final mode should
be used only if the database is already closed and dismounted.
Otherwise, the method might wait indefinitely.
■ If the specified shutdownMode is
OracleDBShutdownMode.Final, then the value of the
bCloseDismountAndFinalize input parameter is ignored, as
the database should have been closed and dismounted already.
Invoking this method against an Oracle Real Application Clusters (RAC) database
shuts down only that database instance to which the OracleDatabase object is
connected.
Example
using System;
using Oracle.DataAccess.Client;
namespace Shutdown
{
class Test
{
static void Main()
{
OracleConnection con = null;
OracleDatabase db = null;
string constring = "user id=scott;password=tiger;data source=oracle;" +
"pooling=false;dba privilege=sysdba";
try
{
// Open a connection to see if the DB is up;
con = new OracleConnection(constring);
con.Open();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
■ "OracleDBShutdownMode Enumeration" on page 5-355
Startup
Startup methods enable a user with database administrator privileges to start a
database instance.
Overload List
■ Startup()
This method starts a database instance using the server-side parameter file.
■ Startup(OracleDBStartupMode, string, bool)
This method starts a database instance using the client-side parameter file.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
■ "OracleDBStartupMode Enumeration" on page 5-356
Startup()
This method starts up the database.
Declaration
// C#
public void Startup();
Exceptions
OracleException - The database startup request has failed.
Remarks
This method starts a database instance in the OracleDbStartupMode.Normal mode
using the server-side parameter file (spfile). After the database is successfully
started, this method also executes the ALTER DATABASE MOUNT and ALTER
DATABASE OPEN statements.
This method does not throw exceptions for cases where the database is already
mounted, opened, or started appropriately. If other errors are encountered, then an
exception is thrown.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
■ "OracleDBStartupMode Enumeration" on page 5-356
Declaration
// C#
public void Startup(OracleDbStartupMode startupMode, string pfile, bool
bMountAndOpen);
Parameters
■ startupMode
An OracleDBStartupMode enumeration value.
■ pfile
The location and name of the client-side parameter file. For example,
"c:\\admin\\init.ora".
The name of the parameter file varies depending on the operating system. For
example, it can be in mixed case or lowercase, or it can have a logical name or a
variation of the name init.ora. The default location is usually ORACLE_
HOME/dbs or ORACLE_HOME\database.
■ bMountAndOpen
A true/false value signifying whether the database is to be mounted and
opened.
Exceptions
OracleException - The database startup request has failed.
Remarks
This method starts a database instance in the specified mode using the specified
client-side parameter file. After the database is successfully started, and if
bMountAndOpen input parameter is true, this method also executes the ALTER
DATABASE MOUNT and ALTER DATABASE OPEN statements.
If bMountAndOpen is true, then this method does not throw an exception for cases
where the database is already mounted, opened, or started appropriately. If other
errors are encountered, then an exception is thrown.
If bMountAndOpen is false, then the database must be mounted and opened
explicitly by the application. For example, if db is an instance of the
OracleDatabase class, then the application invokes the following:
1. db.Startup(OracleDBStartupMode.NoRestriction, null, false);
2. db.ExecuteNonQuery("ALTER DATABASE MOUNT");
3. db.ExecuteNonQuery("ALTER DATABASE OPEN");
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDatabase Class
■ OracleDatabase Members
■ "OracleDBStartupMode Enumeration" on page 5-356
OracleDataReader Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.Data.Common.DataReader
System.Data.Common.DbDataReader (ADO.NET 2.0 only)
Oracle.DataAccess.Client.OracleDataReader
Declaration
// ADO.NET 2.0: C#
public sealed class OracleDataReader : DbDataReader, 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.
To minimize the number of open database cursors, OracleDataReader objects
should be explicitly disposed.
Example
The following OracleDataReader example retrieves the data from the EMP table:
/* Database Setup, if you have not done so yet.
connect scott/tiger@oracle
CREATE TABLE empInfo (
empno NUMBER(4) PRIMARY KEY,
empName VARCHAR2(20) NOT NULL,
hiredate DATE,
salary NUMBER(7,2),
jobDescription Clob,
byteCodes BLOB
);
*/
// 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();
if (!reader.IsDBNull(3))
{
salary = reader.GetDouble(3);
Console.WriteLine("Salary: " + salary);
}
if (!reader.IsDBNull(4))
{
jobDesc = reader.GetString(4);
if (!reader.IsDBNull(5))
{
long len = reader.GetBytes(5, 0, byteCodes, 0, 10);
Console.WriteLine();
}
Console.WriteLine();
}
// Clean up
reader.Dispose();
con.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Members
■ OracleDataReader Static Methods
■ OracleDataReader Properties
■ OracleDataReader Public Methods
■ OracleDataReader SchemaTable
OracleDataReader Members
OracleDataReader Properties
OracleDataReader properties are listed in Table 5–44.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
OracleDataReader Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
Depth
This property gets a value indicating the depth of nesting for the current row.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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 database round-trip.
The RowSize and FetchSize properties handle UDT and XMLType data differently
than other scalar data types. Because only a reference to the UDT and XMLType data is
stored in the ODP.NET's internal cache, the RowSize property accounts for only the
memory needed for the reference (which is very small) and not the actual size of the
UDT and XMLType data. Thus, applications can inadvertently fetch a large number of
UDT or XMLType instances from the database in a single database round-trip. This is
because the actual size of UDT and XMLType data does not count against the
FetchSize, and it would require numerous UDT and XMLType references to fill up
the default cache size of 131072 bytes. Therefore, when fetching UDT or XMLType
data, the FetchSize property must be appropriately configured to control the
number of UDT and XMLType instances that are to be fetched, rather than the amount
of the actual UDT and XMLType data to be fetched.
NOTE: For LOB and LONG data types, only the sizes specified in the
InitialLOBFetchSize and InitialLONGFetchSize properties are accounted for
by the RowSize property in addition to the metadata and reference information that is
maintained by the cache for each LOB in the select list.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ OracleDataReader "RowSize" on page 166
■ OracleCommand "ExecuteReader()" on page 5-34
■ OracleCommand "RowSize" on page 5-23
FieldCount
This property returns the number of columns in the result set.
Declaration
// ADO.NET 2.0: C#
public override int FieldCount {get;}
Property Value
The number of columns in the result set if one exists, otherwise 0.
Implements
IDataRecord
Exceptions
InvalidOperationException - The reader is closed.
Remarks
Default = 0
This property has a value of 0 for queries that do not return result sets.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
HasRows
This property indicates whether the OracleDataReader has one or more rows.
Declaration
// ADO.NET 2.0: C#
public override bool HasRows {get;}
Return Value
bool
Remarks
HasRows indicates whether or not 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 determine 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();
if (!reader.HasRows)
Console.WriteLine("The result set is empty.");
else
Console.WriteLine("The result set is not empty.");
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ http://msdn.microsoft.com/library for detailed
information about this Microsoft .NET Framework 1.1 feature
HiddenFieldCount
This property gets the number of fields in the OracleDataReader that are hidden.
Supported Only in ADO.NET 2.0-Compliant ODP.NET
Declaration
// C#
public int HiddenFieldcount { get; }
Property Value
The number of fields in the OracleDataReader that are hidden.
Exceptions
InvalidOperationException - The reader is closed.
Remarks
OracleDataReader.FieldCount and
OracleDataReader.VisibleFieldCount return the visible field count.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "VisibleFieldCount" on page 5-166
■ "FieldCount" on page 5-160
IsClosed
This property indicates whether or not the data reader is closed.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
Item
This property gets the value of the column in .NET data type.
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-3
■ OracleDataReader Class
■ OracleDataReader Members
Item [index]
This property gets the .NET Value of the column specified by the column index.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
Item [string]
This property gets the .NET Value of the column specified by the column name.
Declaration
// ADO.NET 2.0: C#
public override object this[string columnName] {get;}
Parameters
■ columnName
The name of the column.
Property Value
The .NET Value of the specified column.
Implements
IDataRecord
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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
For Oracle Database 10g release 2 (10.2) and later, the maximum value supported for
InitialLOBFetchSize is 2 GB.
For releases prior to Oracle Database 10g release 2 (10.2), the maximum value
supported for InitialLOBFetchSize is 32K.
Default is the OracleCommand.InitialLOBFetchSize, from which this value is
inherited.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "InitialLOBFetchSize" on page 5-18 for further information on
OracleCommand.InitialLOBFetchSize
■ "Obtaining LOB Data" on page 3-52
InitialLONGFetchSize
This property specifies the amount that the OracleDataReader initially fetches for
LONG and LONG RAW columns.
Declaration
// C#
public long InitialLONGFetchSize {get;}
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "InitialLONGFetchSize" on page 5-20 for further information on
OracleCommand.InitialLONGFetchSize
■ "Obtaining LONG and LONG RAW Data" on page 3-51
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-3
■ OracleDataReader Class
■ OracleDataReader Members
RowSize
This property gets the amount of memory the internal cache of the
OracleDataReader needs to store one row of data.
Declaration
// C#
public long RowSize {get;}
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
The RowSize property is set to a nonzero value when the OracleDataReader object
is created. This property can be used at design time or dynamically during run time, to
set the FetchSize property, based on the number of rows. For example, to enable the
OracleDataReader object to fetch N rows for each database round-trip, the
OracleDataReader FetchSize property can be set dynamically to RowSize * N.
Note that for the FetchSize property to take effect appropriately, it must be set
before the first invocation of OracleDataReader.Read() for the particular result
set.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "FetchSize" on page 159
VisibleFieldCount
This property gets the number of fields in the OracleDataReader that are not
hidden.
Supported Only in ADO.NET 2.0-Compliant ODP.NET
Declaration
// C#
public override int VisibleFieldcount { get; }
Property Value
The number of fields that are not hidden.
Exceptions
InvalidOperationException - The reader is closed.
Remarks
If an application sets the AddRowid property on an OracleCommand object to true,
then the application can access the RowId but it is not a visible field. If RowId is added
in the select statement list, then it is a visible field.
OracleDataReader.VisibleFieldCount and
OracleDataReader.FieldCount always have the same value.
Example
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class VisibleFieldCountSample
{
static void Main(string[] args)
{
string constr = "User Id=scott; Password=tiger; Data Source=oracle;";
DbProviderFactory factory =
DbProviderFactories.GetFactory("Oracle.DataAccess.Client");
reader.Dispose();
cmd.Dispose();
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
Console.WriteLine(ex.StackTrace);
}
}
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "VisibleFieldCount" on page 5-166
■ "FieldCount" on page 5-160
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
Close
This method closes the OracleDataReader.
Declaration
// ADO.NET 2.0: C#
public override 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 5-150.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetBoolean
This method is not supported.
Declaration
// ADO.NET 2.0: C#
public override bool GetBoolean(int index);
Parameters
■ index
The zero-based column index.
Implements
IDataRecord
Exceptions
NotSupportedException - This property is not supported.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetByte
This method returns the byte value of the specified column.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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
// ADO.NET 2.0: C#
public override 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
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetChar
This method is not supported.
Declaration
// ADO.NET 2.0: C#
public override long GetChar(int index);
Parameters
■ index
The zero based column index.
Implements
IDataRecord
Exceptions
NotSupportedException - This property is not supported.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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
// ADO.NET 2.0: C#
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
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetDataTypeName
This method returns the ODP.NET type name of the specified column.
Declaration
// ADO.NET 2.0: C#
Parameters
■ index
The zero-based column index.
Return Value
The name of the ODP.NET type of the column.
Implements
IDataRecord
Exceptions
InvalidOperationException - The reader is closed.
IndexOutOfRangeException - The column index is invalid.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetDateTime
This method returns the DateTime value of the specified column.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetDecimal
This method returns the decimal value of the specified NUMBER column.
Declaration
// ADO.NET 2.0: C#
public override decimal GetDecimal(int index);
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetDouble
This method returns the double value of the specified NUMBER column or BINARY_
DOUBLE column.
Declaration
// ADO.NET 2.0: C#
public override double GetDouble(int index);
Parameters
■ 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.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetEnumerator
This method returns an IEnumerator that can be used to iterate through the
collection (record set).
Declaration
// ADO.NET 2.0: C#
public override IEnumerator GetEnumerator();
Return Value
An IEnumerator that can be used to iterate through the collection (record set).
Exceptions
InvalidOperationException - The reader is closed.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetFieldType
This method returns the type of the specified column.
Declaration
// ADO.NET 2.0: C#
public override 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, or the specified column is a
UDT but no registered custom type mapping exists for the UDT.
IndexOutOfRangeException - The column index is invalid.
Remarks
GetFieldType returns a type that corresponds to the value that the application
obtains after invoking the GetValue accessor or Item property on the
OracleDataReader. For example, if the column is a string, this method returns a
.NET Type object for a .NET string.
If the attribute is a UDT, this method may return either of the following:
■ A .NET Type of the custom type if a custom type mapping exists for the Oracle
object or collection.
■ A .NET Type of string if the column is an Oracle REF.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetFloat
This method returns the float value of the specified NUMBER column or BINARY_
FLOAT column.
Declaration
// ADO.NET 2.0: C#
public override float GetFloat(int index);
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetGuid
This method is not supported.
Declaration
// ADO.NET 2.0: C#
public override Guid GetGuid(int index);
Parameters
■ index
The zero-based column index.
Implements
IDataRecord
Exceptions
NotSupportedException - This property is not supported.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetInt16
This method returns the Int16 value of the specified NUMBER column.
Declaration
// ADO.NET 2.0: C#
public override short GetInt16(int index);
Parameters
■ index
The zero-based column index.
Return Value
The Int16 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-3
■ OracleDataReader Class
■ OracleDataReader Members
GetInt32
This method returns the Int32 value of the specified NUMBER column.
Declaration
// ADO.NET 2.0: C#
public override 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-3
■ OracleDataReader Class
■ OracleDataReader Members
GetInt64
This method returns the Int64 value of the specified NUMBER column.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetName
This method returns the name of the specified column.
Declaration
// ADO.NET 2.0: C#
public override string GetName(int index);
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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-3
■ OracleDataReader Class
■ OracleDataReader Members
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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.
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 database 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.
/* Database Setup, if you have not done so yet.
connect scott/tiger@oracle
CREATE TABLE empInfo (
empno NUMBER(4) PRIMARY KEY,
empName VARCHAR2(20) NOT NULL,
hiredate DATE,
salary NUMBER(7,2),
jobDescription Clob,
byteCodes BLOB
);
*/
// 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();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "LOB Support" on page 3-61
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.
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 database 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 5-186 for a code example demonstrating usage.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "LOB Support" on page 3-61
GetOracleClob
This method returns an OracleClob object of the specified CLOB column.
Declaration
// C#
public OracleClob GetOracleClob(int index);
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.
Remarks
IsDBNull should be called to check for NULL values before calling this method.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "LOB Support" on page 3-61
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.
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 database 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.
/* Database Setup, if you have not done so yet.
connect scott/tiger@oracle
CREATE TABLE empInfo (
empno NUMBER(4) PRIMARY KEY,
empName VARCHAR2(20) NOT NULL,
hiredate DATE,
salary NUMBER(7,2),
jobDescription Clob,
byteCodes BLOB
);
*/
// 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();
if (!reader.IsDBNull(0))
{
jobDescClob = reader.GetOracleClobForUpdate(0);
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "LOB Support" on page 3-61
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.
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 database 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 5-191
for a code example demonstrating usage.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "LOB Support" on page 3-61
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "LOB Support" on page 3-61
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.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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-3
■ OracleDataReader Class
■ OracleDataReader Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetOracleRef
This method returns an OracleRef object of the specified REF column.
Declaration
// C#
public OracleRef GetOracleRef(int index);
Parameters
■ index
The zero-based column index.
Return Value
The OracleRef object of the specified column.
Exceptions
InvalidOperationException - The connection is closed, the reader is closed, the
Read method has not been called, or all rows have been read.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetOracleString
This method returns an OracleString structure of the specified column.
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.
IndexOutOfRangeException - The column index is invalid.
InvalidCastException - The accessor method is invalid for this column type or
the column value is NULL.
Remarks
If the column is an Oracle REF column, the string returned is a hexadecimal value that
represents the REF in the database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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.
Remarks
GetOracleTimeStamp is used with the Oracle Type TimeStamp.
IsDBNull should be called to check for NULL values before calling this method.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetOracleTimeStampTZ
This method returns an OracleTimeStampTZ structure of the specified Oracle
TimeStamp WITH TIME ZONE column.
Declaration
// C#
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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 later.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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.
Remarks
If the column is an Oracle object or Oracle collection column and a custom type
mapping exists, then a custom type is returned.
If the column is an Oracle REF column, then an OracleRef is returned.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
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.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
■ "LOB Support" on page 3-61
GetOrdinal
This method returns the 0-based ordinal (or index) of the specified column name.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetProviderSpecificFieldType
This method returns the provider-specific type of the specified column.
Declaration
// ADO.NET 2.0: C#
public override Type GetProviderSpecificFieldType(int index);
Parameters
■ index
A zero-based column index.
Return Value
The provider-specific type of the specified column. This is a member of the
Oracle.DataAccess.Types namespace.
Exceptions
IndexOutOfRangeException - The column index is invalid.
InvalidOperationException - The reader is closed, or the specified column is a
UDT but no registered custom type mapping exists for the UDT.
Remarks
GetProviderSpecficFieldType returns a type that corresponds to the value the
application obtains after invoking the GetProviderSpecificValue accessor on the
OracleDataReader. For example, if the column is a string, this method returns a
.NET Type object for an OracleString.
If the attribute is a UDT, this method may return any of the following:
■ A .NET Type of the custom type, if the column is an Oracle object or Oracle
collection column and a custom type mapping exists.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetProviderSpecificValue
This method returns an object that represents the underlying provider-specific value of
the specified ordinal.
Declaration
// ADO.NET 2.0: C#
public override object GetProviderSpecificValue (int index);
Parameters
index
A zero-based column index.
Return Value
An Object that is a representation of the underlying provider-specific field type.
Exceptions
IndexOutOfRangeException - The column index is invalid.
InvalidOperationException - The connection is closed, the reader is closed,
Read() has not been called or all rows have been read.
Remarks
If the column is an Oracle object or collection column, and a custom type mapping
exists, a custom type is returned.
If the column is an Oracle REF column, an OracleRef is returned.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetProviderSpecificValues
This method returns an array of objects that represent the underlying provider-specific
values.
Declaration
// ADO.NET 2.0: C#
public override int GetProviderSpecificValues(object [ ] values);
Parameters
■ values
An array of objects.
Return Value
The number of Object instances in the array.
Exceptions
InvalidOperationException - The reader is closed.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetSchemaTable
This method returns a DataTable that describes the column metadata of the
OracleDataReader.
Declaration
// ADO.NET 2.0: C#
public override 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
The OracleDataReader.GetSchemaTable method 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.
Example
This example creates and uses the SchemaTable from the reader.
/* Database Setup, if you have not done so yet.
connect scott/tiger@oracle
CREATE TABLE empInfo (
empno NUMBER(4) PRIMARY KEY,
empName VARCHAR2(20) NOT NULL,
hiredate DATE,
salary NUMBER(7,2),
jobDescription Clob,
byteCodes BLOB
);
*/
// 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();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetString
This method returns the string value of the specified column.
Declaration
// ADO.NET 2.0: C#
public override 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
Call the IsDBNull method to check for null values before calling this method.
If the column is an Oracle REF column, the string returned is a hexadecimal string that
represents the REF in the database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetTimeSpan
This method returns the TimeSpan value of the specified INTERVAL DAY TO SECOND
column.
Declaration
// C#
public TimeSpan GetTimeSpan(int index);
Parameters
■ index
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetValue
This method returns the column value as a .NET type.
Declaration
// ADO.NET 2.0: C#
public override 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, all rows have been read, or no valid custom type
mapping has been specified for the Oracle Object or Oracle Collection column.
IndexOutOfRangeException - The column index is invalid.
Remarks
If the column is an Oracle Object or an Oracle Collection column, the .NET custom
type corresponding to the custom type mapping is returned.
If the column is an Oracle REF column, a hexidecimal value is returned as a .NET
string that represents the REF in the database.
If the UDT is NULL, DBNull.Value is returned
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetValues
This method gets all the column values as .NET types.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
GetXmlReader
This method returns the contents of an XMLType column as an instance of an .NET
XmlTextReader object.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
IsDBNull
This method indicates whether or not the column value is NULL.
Declaration
// ADO.NET 2.0: C#
public override 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.
Example
The code example for the OracleDataReader class includes the IsDBNull method.
See "Example" on page 5-150.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
NextResult
This method advances the data reader to the next result set.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
Read
This method reads the next row in the result set.
Declaration
// ADO.NET 2.0: C#
public override 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.
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 5-150.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataReader Class
■ OracleDataReader Members
OracleError Class
Class Inheritance
System.Object
Oracle.DataAccess.Client.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.
If there are multiple errors, ODP.NET only returns the first error message on the stack.
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();
try
{
cmd.CommandText = "insert into notable values (99, 'MyText')";
cmd.ExecuteNonQuery();
}
catch (OracleException ex)
{
Console.WriteLine("Record is not inserted into the database table.");
}
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Members
■ OracleError Static Methods
■ OracleError Properties
■ OracleError Methods
OracleError Members
OracleError Properties
OracleError properties are listed in Table 5–51.
OracleError Methods
OracleError methods are listed in Table 5–52.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
■ OracleError Members
OracleError Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
■ OracleError Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
■ OracleError Members
■ "Array Binding" on page 3-39
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
■ OracleError Members
Message
This property specifies the message describing the error.
Declaration
// C#
public string Message {get;}
Property Value
A string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
■ OracleError Members
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-3
■ OracleError Class
■ OracleError Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
■ OracleError Members
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-3
■ OracleError Class
■ OracleError Members
OracleError Methods
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
■ OracleError Members
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleError Class
■ OracleError Members
OracleErrorCollection Class
Class Inheritance
System.Object
System.ArrayList
Oracle.DataAccess.Client.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.
If there are multiple errors, ODP.NET only returns the first error message on the stack.
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();
try
{
cmd.CommandText = "insert into notable values (99, 'MyText')";
cmd.ExecuteNonQuery();
}
catch (OracleException ex)
{
Console.WriteLine("Record is not inserted into the database table.");
}
}
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleErrorCollection Members
■ OracleErrorCollection Static Methods
■ OracleErrorCollection Properties
■ OracleErrorCollection Public Methods
OracleErrorCollection Members
OracleErrorCollection Properties
OracleErrorCollection properties are listed in Table 5–57.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleErrorCollection Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleErrorCollection Class
■ OracleErrorCollection Members
OracleErrorCollection Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleErrorCollection Class
■ OracleErrorCollection Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleErrorCollection Class
■ OracleErrorCollection Members
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
System.Object
System.Exception
System.SystemException
System.Runtime.InteropServices.ExternalException (ADO.NET
2.0 only)
System.Data.Common.DbException (ADO.NET 2.0 only)
Oracle.DataAccess.Client.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.
Remarks
If there are multiple errors, ODP.NET only returns the first error message on the stack.
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();
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);
}
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Members
■ OracleException Methods
■ OracleException Static Methods
■ OracleException Static Methods
■ OracleException Properties
■ OracleException Methods
OracleException Members
OracleException Properties
OracleException properties are listed in Table 5–63.
OracleException Methods
OracleException methods are listed in Table 5–64.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
■ OracleException Members
OracleException Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
■ OracleException Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
■ OracleException Members
Errors
This property specifies a collection of one or more OracleError objects that contain
information about exceptions generated by the Oracle database.
Declaration
// C#
public OracleErrorCollection Errors {get;}
Property Value
An OracleErrorCollection.
Remarks
The Errors property contains at least one instance of OracleError objects.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
■ OracleException Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
■ OracleException Members
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-3
■ OracleException Class
■ OracleException Members
Procedure
This property specifies the stored procedure that caused the exception.
Declaration
// C#
public string Procedure {get;}
Property Value
The stored procedure name.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
■ OracleException Members
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-3
■ OracleException Class
■ OracleException Members
OracleException Methods
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
■ OracleException Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleException Class
■ OracleException Members
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();
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-3
■ OracleException Class
■ OracleException Members
OracleInfoMessageEventArgs Class
Class Inheritance
System.Object
System.EventArgs
Oracle.DataAccess.Client.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();
cmd.CommandText =
"create or replace procedure SelectWithNoInto( " +
" empname in VARCHAR2) AS " +
"BEGIN " +
" select * from emp where ename = empname; " +
"END SelectWithNoInto;";
// Clean up
cmd.Dispose();
con.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleInfoMessageEventArgs Members
■ OracleInfoMessageEventArgs Static Methods
■ OracleInfoMessageEventArgs Properties
■ OracleInfoMessageEventArgs Public Methods
■ "OracleConnection Class" on page 5-64
OracleInfoMessageEventArgs Members
OracleInfoMessageEventArgs Properties
The OracleInfoMessageEventArgs properties are listed in Table 5–69.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleInfoMessageEventArgs Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleInfoMessageEventArgs Class
■ OracleInfoMessageEventArgs Members
OracleInfoMessageEventArgs Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleInfoMessageEventArgs Class
■ OracleInfoMessageEventArgs Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleInfoMessageEventArgs Class
■ OracleInfoMessageEventArgs Members
Message
This property specifies the error text generated by the data source.
Declaration
// C#
public string Message {get;}
Property Value
The error text.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleInfoMessageEventArgs Class
■ OracleInfoMessageEventArgs Members
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-3
■ OracleInfoMessageEventArgs Class
■ OracleInfoMessageEventArgs Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleInfoMessageEventArgs Class
■ OracleInfoMessageEventArgs Members
OracleInfoMessageEventHandler Delegate
Declaration
// C#
public delegate void OracleInfoMessageEventHandler(object sender,
OracleInfoMessageEventArgs eventArgs);
Parameters
■ sender
The source of the event.
■ eventArgs
The OracleInfoMessageEventArgs object that contains the event data.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "InfoMessage" on page 5-112
OracleParameter Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.Data.Common.DbParameter (ADO.NET 2.0 only)
Oracle.DataAccess.Client.OracleParameter
Declaration
// ADO.NET 2.0: C#
public sealed class OracleParameter : DbParameter, 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();
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Members
■ OracleParameter Constructors
■ OracleParameter Static Methods
■ OracleParameter Properties
■ OracleParameter Public Methods
OracleParameter Members
OracleParameter Constructors
OracleParameter constructors are listed in Table 5–74.
OracleParameter Properties
OracleParameter properties are listed in Table 5–76.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
OracleParameter Constructors
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 data type.
■ 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, data type, and parameter direction.
■ OracleParameter(string, OracleDbType, object, ParameterDirection)
This constructor instantiates a new instance of the OracleParameter class using
the supplied parameter name, data type, value, and direction.
■ OracleParameter(string, OracleDbType, int)
This constructor instantiates a new instance of the OracleParameter class using
the supplied parameter name, data type, and size.
■ OracleParameter(string, OracleDbType, int, string)
This constructor instantiates a new instance of the OracleParameter class using
the supplied parameter name, data type, 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, data type, 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, data type, size, value, and direction.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
OracleParameter()
This constructor instantiates a new instance of OracleParameter class.
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
■ "OracleParameterCollection Class" on page 5-281
Declaration
// C#
public OracleParameter(string parameterName, OracleDbType oraType);
Parameters
■ parameterName
The parameter name.
■ oraType
The data type of the OracleParameter.
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
■ "OracleParameterCollection Class" on page 5-281
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
The parameter name.
■ obj
The value of the OracleParameter.
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-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
■ "OracleParameterCollection Class" on page 5-281
Declaration
// C#
public OracleParameter(string parameterName, OracleDbType type,
ParameterDirection direction);
Parameters
■ parameterName
The parameter name.
■ type
The data type of the OracleParameter.
■ direction
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
■ 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-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
■ "OracleParameterCollection Class" on page 5-281
Declaration
// C#
public OracleParameter(string parameterName, OracleDbType type, object obj,
ParameterDirection direction);
Parameters
■ parameterName
The parameter name.
■ type
The data type of the OracleParameter.
■ obj
The value of the OracleParameter.
■ direction
The ParameterDirection value.
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
■ "OracleParameterCollection Class" on page 5-281
Declaration
// C#
public OracleParameter(string parameterName, OracleDbType type,
int size);
Parameters
■ parameterName
The parameter name.
■ type
The data type of the OracleParameter.
■ size
The size of the OracleParameter value.
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-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
■ "OracleParameterCollection Class" on page 5-281
Declaration
// C#
public OracleParameter(string parameterName, OracleDbType type, int size,
string srcColumn);
Parameters
■ parameterName
The parameter name.
■ type
The data type of the OracleParameter.
■ size
The size of the OracleParameter value.
■ srcColumn
The name of the source column.
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-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
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
The parameter name.
■ oraType
The data type of the OracleParameter.
■ size
The size of the OracleParameter value.
■ direction
The ParameterDirection value.
■ isNullable
An indicator that specifies if the parameter value can be null.
■ precision
The precision of the parameter value.
■ scale
The scale of the parameter value.
■ srcColumn
The name of the source column.
■ srcVersion
The DataRowVersion value.
■ obj
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-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
Declaration
// C#
public OracleParameter(string parameterName, OracleDbType type, int size,
object obj, ParameterDirection direction);
Parameters
■ parameterName
The parameter name.
■ type
The data type of the OracleParameter.
■ size
The size of the OracleParameter value.
■ obj
The value of the OracleParameter.
■ direction
The ParameterDirection value.
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
■ "OracleParameterCollection Class" on page 5-281
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
OracleParameter Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
ArrayBindSize
This property specifies the maximum size, in bytes or characters, of the data for each
array element transmitted to or from the database. This property is used for Array
Bind or PL/SQL Associative Array execution.
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();
cmd.CommandText =
"insert into emp(empno, ename, deptno) values(:1, :2, :3)";
cmd.ExecuteNonQuery();
prm[0].Dispose();
prm[1].Dispose();
prm[2].Dispose();
cmd.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "ArrayBindCount" on page 5-13
■ "Size" on page 5-271 and "Value" on page 5-275 for more
information on binding Associative Arrays
■ "ArrayBindStatus" on page 5-264
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-3
■ OracleParameter Class
■ OracleParameter Members
■ "ArrayBindCount" on page 5-13
■ "OracleParameterStatus Enumeration" on page 5-359
■ "Value" on page 5-275 for more information on binding
Associative Arrays
■ "ArrayBindSize" on page 5-263
CollectionType
This property specifies whether or not 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
DbType
This property specifies the data type of the parameter using the Data.DbType
enumeration type.
Declaration
// ADO.NET 2.0: C#
public override DbType DbType {get; set; }
Property Value
A DbType enumerated value.
Implements
IDataParameter
Exceptions
ArgumentException - The DbType value specified is invalid.
Remarks
Default = DbType.String
DbType is the data type 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "Inference of OracleDbType from DbType" on page 3-34
■ "CollectionType" on page 5-265
Direction
This property specifies whether the parameter is input-only, output-only,
bi-directional, or a stored function return value parameter.
Declaration
// ADO.NET 2.0: C#
public override 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
IsNullable
This property is not supported.
Declaration
// ADO.NET 2.0: C#
public override bool IsNullable { get; set; }
Implements
IDataParameter
Property Value
This property is not supported.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
Offset
This property specifies the offset to the Value property.
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
OracleDbType
This property specifies the Oracle data type.
Declaration
// C#
public OracleDbType OracleDbType { get; set; }
Property Value
An OracleDbType enumerated value.
Remarks
Default = OracleDbType.Varchar2
If the OracleParameter object is used for Array Bind or PL/SQL Associative Array
Bind execution, OracleDbType is the data type 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleDbType Enumeration" on page 5-357
■ "Inference of DbType from OracleDbType" on page 3-33
■ "CollectionType" on page 5-265
OracleDbTypeEx
This property specifies the Oracle data type to bind the parameter as, but returns a
.NET type as output.
Declaration
// C#
public OracleDbType OracleDbTypeEx { get; set; }
Property Value
An OracleDbType enumerated value.
Remarks
This property is used by applications that need to bind a parameter value as an Oracle
type, but need a .NET type back for output. This property should be used with an
output or input/output parameter. For an input parameter, using OracleDbTypeEx
has the same affect as using OracleDbType. The .NET type that is returned for the
output is the .NET type that the Oracle type closely maps to.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleDbType Enumeration" on page 5-357
■ "OracleDbType" on page 5-268
■ "Inference of DbType from OracleDbType" on page 3-33
■ "CollectionType" on page 5-265
ParameterName
This property specifies the name of the parameter.
Declaration
// ADO.NET 2.0: C#
public override string ParameterName { get; set; }
Property Value
String
Implements
IDataParameter
Remarks
Default = null
Oracle supports ParameterName up to 30 characters.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
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
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "Value" on page 5-275
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "Value" on page 5-275
Size
This property specifies the maximum size, in bytes or characters, of the data
transmitted to or from the database.
Declaration
// ADO.NET 2.0: C#
public override int Size { get; set;}
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 data types: ignored
■ Variable length data types: describes the maximum amount of data transmitted to
or from the database. 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.
Note: Size does not include the null terminating character for the
string data.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleDbType Enumeration" on page 5-357
■ "CollectionType" on page 5-265
■ "ArrayBindSize" on page 5-263
■ "ArrayBindStatus" on page 5-264
■ "Value" on page 5-275
SourceColumn
This property specifies the name of the DataTable Column of the DataSet.
Declaration
// ADO.NET 2.0: C#
public override string SourceColumn { get; set; }
Property Value
A string.
Implements
IDataParameter
Remarks
Default = empty string
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
SourceColumnNullMapping
This property specifies a value which indicates whether the source column is nullable.
Declaration
// ADO.NET 2.0: C#
public bool SourceColumnNullMapping { get; set; }
Property Value
Returns true if the source column can be nullified; otherwise, returns false.
Remarks
The default value is false.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
SourceVersion
This property specifies the DataRowVersion value to use when loading the Value
property of the parameter.
Declaration
// ADO.NET 2.0: C#
public override DataRowVersion SourceVersion { get; set; }
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
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
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 if:
■ 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.
This property is ignored for Array Bind and PL/SQL Associative Array Bind.
Instead, ArrayBindStatus property is used.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
■ "OracleParameterStatus Enumeration" on page 5-359
■ "ArrayBindStatus" on page 5-264
UdtTypeName
This property specifies the Oracle user-defined type name if the parameter is a
user-defined data type.
Declaration
// C#
public string UdtTypeName {get; set;}
Property Value
Name of the Oracle UDT.
Remarks
The UdtTypeName property corresponds to the user-defined type name of the
parameter. This property must always be specified if the parameter is a user-defined
type.
Note that when a custom object is provided as an input parameter value, it is
converted to the Oracle UDT that is specified by the custom type mapping on the
connection used to execute the command.
The Oracle UDT specified by the custom type mapping and by the
OracleParamter.UdtTypeName property differs if the application binds a custom
object that represents a subtype of the parameter type.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
Value
This property specifies the value of the Parameter.
Declaration
// ADO.NET 2.0: C#
public override 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-34
■ "ArrayBindCount" on page 5-13
■ "ArrayBindSize" on page 5-263
■ "ArrayBindStatus" on page 5-264
■ "OracleDbType Enumeration" on page 5-357
For input parameters the value is:
■ Bound to the OracleCommand that is sent to the database.
■ Converted to the data type specified in OracleDbType or DbType when the
provider sends the data to the database.
For output parameters the value is:
■ Set on completion of the OracleCommand (true for return value parameters also).
■ Set to the data from the database, to the data type 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-3
■ OracleParameter Class
■ OracleParameter Members
■ "ArrayBindCount" on page 5-13
■ "OracleParameterStatus Enumeration" on page 5-359
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
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
{
static void Main()
{
OracleParameter prm1 = new OracleParameter();
prm1.Dispose();
prm2.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
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-3
■ OracleParameter Class
■ OracleParameter Members
ResetDbType
This method resets the type associated with the parameter so that it can infer its type
from the value passed in the parameter.
Declaration
// ADO.NET 2.0: C#
public override void ResetDbType();
Remarks
If an application does not set the DbType or OracleDbType properties of an
OracleParameter object, then these values are inferred from the value set by the
application to that OracleParameter object. Calling ResetDbType method resets
these properties so that OracleParameter can again infer its type from the value
passed into the OracleParameter. Calling this method affects both the DbType and
OracleDbType properties of the OracleParameter object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
ResetOracleDbType
This method resets the type associated with the parameter so that it can infer its type
from the value passed in the parameter.
Declaration
// ADO.NET 2.0: C#
public override void ResetOracleDbType();
Remarks
If an application does not set the DbType or OracleDbType properties of an
OracleParameter object, then these values are inferred from the value set by the
application to that OracleParameter object. Calling the ResetOracleDbType
method resets these properties so that OracleParameter can again infer its type
from the value passed into the OracleParameter. Calling this method affects both
the DbType and OracleDbType properties of the OracleParameter object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameter Class
■ OracleParameter Members
OracleParameterCollection Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.Data.Common.DbParameterCollection (ADO.NET 2.0 only)
Oracle.DataAccess.Client.OracleParameterCollection
Declaration
// ADO.NET 2.0: C#
public sealed class OracleParameterCollection : DbParameterCollection,
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();
"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();
prm[0].Dispose();
prm[1].Dispose();
prm[2].Dispose();
cmd.Dispose();
con.Close();
con.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Members
■ OracleParameterCollection Static Methods
■ OracleParameterCollection Properties
■ OracleParameterCollection Public Methods
OracleParameterCollection Members
OracleParameterCollection Properties
OracleParameterCollection properties are listed in Table 5–82.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
OracleParameterCollection Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Count
This property specifies the number of OracleParameter objects in the collection.
Declaration
// ADO.NET 2.0: C#
public override int Count {get;}
Property Value
The number of OracleParameter objects.
Implements
ICollection
Remarks
Default = 0
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
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-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Add
Add adds objects to the collection.
Overload List:
■ Add(object)
This method adds the supplied object to the collection.
■ Add(OracleParameter)
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Add(object)
This method adds the supplied object to the collection.
Declaration
// ADO.NET 2.0: C#
public override int Add(object obj);
Parameters
■ obj
The supplied object.
Return Value
The index at which the new OracleParameter is added.
Implements
IList
Remarks
InvalidCastException - The supplied obj cannot be cast to an
OracleParameter object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Add(OracleParameter)
This method adds the supplied OracleParameter object to the collection.
Declaration
// C#
public OracleParameter Add(OracleParameter paramObj);
Parameters
■ paramObj
The supplied OracleParameter object.
Return Value
The newly created OracleParameter object which was added to the collection.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
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
The parameter name.
■ val
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-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
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
The parameter name.
■ dbType
The data type of the OracleParameter.
Return Value
The newly created OracleParameter object which was added to the collection.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Declaration
// C#
public OracleParameter Add(string name, OracleDbType dbType,
ParameterDirection direction);
Parameters
■ name
The parameter name.
■ dbType
The data type of the OracleParameter.
■ direction
The OracleParameter direction.
Return Value
The newly created OracleParameter object which was added to the collection.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
■ "OracleDbType Enumeration" on page 5-357
Declaration
// C#
public OracleParameter Add(string name, OracleDbType dbType, object val,
ParameterDirection dir);
Parameters
■ name
The parameter name.
■ dbType
The data type of the OracleParameter.
■ val
The OracleParameter value.
■ dir
The ParameterDirection value.
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();
prm.Dispose();
cmd.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
■ "OracleDbType Enumeration" on page 5-357
Declaration
// C#
public OracleParameter Add(string name, OracleDbType dbType, int size,
object val, ParameterDirection dir;
Parameters
■ name
The parameter name.
■ dbType
The data type of the OracleParameter.
■ size
The size of OracleParameter.
■ val
The OracleParameter value.
■ dir
The ParameterDirection value.
Return Value
The newly created OracleParameter object which was added to the collection.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
■ "OracleDbType Enumeration" on page 5-357
Declaration
// C#
public OracleParameter Add(string name, OracleDbType dbType, int size);
Parameters
■ name
The parameter name.
■ dbType
The data type of the OracleParameter.
■ size
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();
prm.Dispose();
cmd.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Declaration
// C#
public OracleParameter Add(string name, OracleDbType dbType, int size,
string srcColumn);
Parameters
■ name
The parameter name.
■ dbType
The data type of the OracleParameter.
■ size
The size of OracleParameter.
■ srcColumn
The name of the source column.
Return Value
An OracleParameter.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
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
The parameter name.
■ dbType
The data type of the OracleParameter.
■ size
The size of OracleParameter.
■ dir
The ParameterDirection value.
■ isNullable
An indicator that specifies if the parameter value can be null.
■ precision
The precision of the parameter value.
■ scale
The scale of the parameter value.
■ srcColumn
The name of the source column.
■ version
The DataRowVersion value.
■ val
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
AddRange
This method adds elements to the end of the OracleParameterCollection.
Declaration
// ADO.NET 2.0: C#
public override void AddRange(Array paramArray );
Parameters
paramArray
An array of OracleParameter objects.
Exceptions
ArgumentNullException - The input parameter is null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Clear
This method removes all the OracleParameter objects from the collection.
Declaration
// ADO.NET 2.0: C#
Implements
IList
Example
// C#
using System;
using Oracle.DataAccess.Client;
class ClearSample
{
static void Main()
{
OracleCommand cmd = new OracleCommand();
prm.Dispose();
cmd.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Contains
Contains indicates whether or not the supplied object exists in the collection.
Overload List:
■ Contains(object)
This method indicates whether or not the supplied object exists in the collection.
■ Contains(string)
This method indicates whether or not an OracleParameter object exists in the
collection using the supplied string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Contains(object)
This method indicates whether or not the supplied object exists in the collection.
Declaration
// ADO.NET 2.0: C#
public override bool Contains(object obj)
Parameters
■ obj
The object.
Return Value
A bool that indicates whether or not the OracleParameter specified is inside the
collection.
Implements
IList
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();
prm1.Dispose();
prm2.Dispose();
cmd.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Contains(string)
This method indicates whether or not an OracleParameter object exists in the
collection using the supplied string.
Declaration
// ADO.NET 2.0: C#
public override bool Contains(string name);
Parameters
■ name
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();
prm.Dispose();
cmd.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
CopyTo
This method copies OracleParameter objects from the collection, starting with the
supplied index to the supplied array.
Declaration
// ADO.NET 2.0: C#
public override void CopyTo(Array array, int index);
Parameters
■ array
The specified array.
■ index
The array index.
Implements
ICollection
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
IndexOf(object)
This method returns the index of the OracleParameter object in the collection.
Declaration
// ADO.NET 2.0: C#
public override int IndexOf(object obj);
Parameters
■ obj
The specified object.
Return Value
Returns the index of the OracleParameter object in the collection.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
IndexOf(String)
This method returns the index of the OracleParameter object with the specified
name in the collection.
Declaration
// ADO.NET 2.0: C#
public override int IndexOf(String name);
Parameters
■ name
The name of parameter.
Return Value
Returns the index of the supplied OracleParameter in the collection.
Implements
IDataParameterCollection
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Insert
This method inserts the supplied OracleParameter object to the collection at the
specified index.
Declaration
// ADO.NET 2.0: C#
public override void Insert(int index, object obj);
Parameters
■ index
The specified index.
■ obj
The OracleParameter object.
Implements
IList
Remarks
An InvalidCastException is thrown if the supplied obj cannot be cast to an
OracleParameter object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
Remove
This method removes the supplied OracleParameter from the collection.
Declaration
// ADO.NET 2.0: C#
public override void Remove(object obj);
Parameters
■ obj
The specified 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();
prm1.Dispose();
prm2.Dispose();
cmd.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
RemoveAt(int)
This method removes from the collection the OracleParameter object located at the
index specified by the supplied index.
Declaration
// ADO.NET 2.0: C#
public override void RemoveAt(int index);
Parameters
■ index
The specified index from which the OracleParameter is to be removed.
Implements
IList
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
RemoveAt(String)
This method removes from the collection the OracleParameter object specified by
the supplied name.
Declaration
// ADO.NET 2.0: C#
public override 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-3
■ OracleParameterCollection Class
■ OracleParameterCollection Members
OraclePermission Class
Class Inheritance
System.Object
System.Security.CodeAccessPermission
System.Data.Common.DBDataPermission
Oracle.DataAccess.Client.OraclePermission
Declaration
// ADO.NET 2.0: C#
public class OraclePermission: DBDataPermission
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Members
■ OraclePermission Constructor
■ OraclePermission Static Methods
■ OraclePermission Public Properties
■ OraclePermission Public Methods
OraclePermission Members
OraclePermission Constructors
The OraclePermission constructor is listed in Table 5–87.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Class
OraclePermission Constructor
Declaration
// C#
public OraclePermission (PermissionState state);
Parameters
■ state
The state parameter takes one of the following two values:
PermissionState.None or PermissionState.Unrestricted.
Exceptions
ArgumentException - The PermissionState value is invalid.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Class
■ OraclePermission Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Class
■ OraclePermission Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Class
■ OraclePermission Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Class
■ OraclePermission Members
Add
This method adds a new connection string fragment and a list of restricted keywords
to the OraclePermission object.
Declaration
// C#
public void Add(string connStr, string keyRestrict,
KeyRestrictionBehavior behavior);
Parameters
■ connStr
Exceptions
ArgumentException - The KeyRestrictionBehavior value or the format of the
connStr or keyRestict string is invalid.
Remarks
The Add method configures the connection strings allowed or disallowed by the
permission object.
Opening an OracleConnection is allowed or denied based upon the connection
string fragment, key restrictions combination, and the key restriction behavior.
In the following example, KeyRestrictionBehavior.AllowOnly allows
connection strings that use orcl as the Data Source with any User Id and
Password combination but no other connection string keywords. Connection string
keywords other than User Id and Password cause security exceptions.
orclPermission.Add("Data Source=orcl;","User Id=;Password=;",
KeyRestrictionBehavior.AllowOnly);
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Class
■ OraclePermission Members
Copy
This method returns a copy of the current permission object.
Declaration
// C#
public override IPermission Copy();
Return Value
A copy of the OraclePermission object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Class
■ OraclePermission Members
IsSubsetOf
This method returns a boolean value that indicates whether or not the current
permission is a subset of the target permission.
Declaration
// C#
public override bool IsSubsetOf(IPermission target);
Parameters
■ target
A permission that must be of type OraclePermission.
Return Value
A bool value that indicates whether or not the current permission is a subset of the
target permission.
Exceptions
ArgumentException - The permission is not of the OraclePermission type.
Remarks
The AllowBlankPassword property is ignored when evaluating whether or not the
current permission is a subset of the target permission.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermission Class
■ OraclePermission Members
OraclePermissionAttribute Class
Class Inheritance
System.Object
System.Attribute
System.Security.Permissions.SecurityAttribute
System.Security.Permissions.CodeAccessSecurityAttribute
System.Data.Common.DBDataPermissionAttribute
Oracle.DataAccess.Client.OraclePermissionAttribute
Declaration
// ADO.NET 2.0:C#
[Serializable, AttributeUsage(AttributeTargets.Method |
AttributeTargets.Constructor | AttributeTargets.Class | AttributeTargets.Struct |
AttributeTargets.Assembly, AllowMultiple = true, Inherited = false)]
public sealed class OraclePermissionAttribute: DBDataPermissionAttribute
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermissionAttribute Members
■ OraclePermissionAttribute Constructor
■ OraclePermissionAttribute Static Methods
■ OraclePermissionAttribute Public Properties
■ OraclePermissionAttribute Public Methods
OraclePermissionAttribute Members
OraclePermissionAttribute Constructor
The OraclePermissionAttribute constructor is listed in Table 5–94.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermissionAttribute Class
OraclePermissionAttribute Constructor
Declaration
// C#
public OraclePermissionAttribute (SecurityAction action);
Parameters
■ action
A System.Security.Permissions.SecurityAction value representing an
action that can be performed using declarative security.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermissionAttribute Class
■ OraclePermissionAttribute Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermissionAttribute Class
■ OraclePermissionAttribute Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermissionAttribute Class
■ OraclePermissionAttribute Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermissionAttribute Class
■ OraclePermissionAttribute Members
CreatePermission
This method returns a new OraclePermissionAttribute object that is configured
based on the attributes set.
Declaration
// C#
public override IPermission CreatePermission();
Return Value
An OraclePermission object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OraclePermissionAttribute Class
■ OraclePermissionAttribute Members
OracleRowUpdatedEventArgs Class
Class Inheritance
System.Object
System.EventArgs
System.RowUpdatedEventArgs
System.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 RowUpdated event "Example" on page 5-135.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatedEventArgs Members
■ OracleRowUpdatedEventArgs Constructor
■ OracleRowUpdatedEventArgs Static Methods
■ OracleRowUpdatedEventArgs Properties
■ OracleRowUpdatedEventArgs Public Methods
■ OracleDataAdapter Class on page 5-114
OracleRowUpdatedEventArgs Members
OracleRowUpdatedEventArgs Constructors
OracleRowUpdatedEventArgs constructors are listed in Table 5–101.
OracleRowUpdatedEventArgs Properties
The OracleRowUpdatedEventArgs properties are listed in Table 5–103.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatedEventArgs Class
OracleRowUpdatedEventArgs Constructor
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-3
■ OracleRowUpdatedEventArgs Class
■ OracleRowUpdatedEventArgs Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatedEventArgs Class
■ OracleRowUpdatedEventArgs Members
OracleRowUpdatedEventArgs Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatedEventArgs Class
■ OracleRowUpdatedEventArgs Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatedEventArgs Class
■ OracleRowUpdatedEventArgs Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatedEventArgs Class
■ OracleRowUpdatedEventArgs Members
OracleRowUpdatedEventHandler Delegate
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.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "RowUpdated" on page 5-134
OracleRowUpdatingEventArgs Class
Class Inheritance
System.Object
System.EventArgs
System.RowUpdatingEventArgs
System.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 RowUpdated event "Example" on page 5-135.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatingEventArgs Members
■ OracleRowUpdatingEventArgs Constructor
■ OracleRowUpdatingEventArgs Static Methods
■ OracleRowUpdatingEventArgs Properties
■ OracleRowUpdatingEventArgs Public Methods
■ "OracleDataAdapter Class" on page 5-114
OracleRowUpdatingEventArgs Members
OracleRowUpdatingEventArgs Constructors
OracleRowUpdatingEventArgs constructors are listed in Table 5–108.
OracleRowUpdatingEventArgs Properties
The OracleRowUpdatingEventArgs properties are listed in Table 5–110.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatingEventArgs Class
OracleRowUpdatingEventArgs Constructor
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-3
■ OracleRowUpdatingEventArgs Class
■ OracleRowUpdatingEventArgs Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatingEventArgs Class
■ OracleRowUpdatingEventArgs Members
OracleRowUpdatingEventArgs Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatingEventArgs Class
■ OracleRowUpdatingEventArgs Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatingEventArgs Class
■ OracleRowUpdatingEventArgs Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowUpdatingEventArgs Class
■ OracleRowUpdatingEventArgs Members
OracleRowUpdatingEventHandler Delegate
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.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "RowUpdating" on page 5-136
OracleTransaction Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.Data.Common.DbTransaction (ADO.NET 2.0 only)
Oracle.DataAccess.Client.OracleTransaction
Declaration
// ADO.NET 2.0: C#
public sealed class OracleTransaction : DbTransaction
// 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 Read Committed mode only. 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, if you have not done so yet.
/*
connect scott/tiger@oracle
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
{
// 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.
// 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);
txn.Dispose();
cmd.Dispose();
con.Close();
con.Dispose();
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
Comment: Not supported in a .NET stored procedure
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Members
■ OracleTransaction Static Methods
■ OracleTransaction Properties
OracleTransaction Members
OracleTransaction Properties
OracleTransaction properties are listed in Table 5–116.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
OracleTransaction Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
IsolationLevel
This property specifies the isolation level for the transaction.
Declaration
// ADO.NET 2.0: C#
public override IsolationLevel IsolationLevel {get;}
Property Value
IsolationLevel
Implements
IDbTransaction
Exceptions
InvalidOperationException - The transaction has already completed.
Remarks
Default = IsolationLevel.ReadCommitted
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
Connection
This property specifies the connection that is associated with the transaction.
Declaration
// C#
public OracleConnection Connection {get;}
Property Value
Connection
Implements
IDbTransaction
Remarks
This property indicates the OracleConnection object that is associated with the
transaction.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
Commit
This method commits the database transaction.
Declaration
// ADO.NET 2.0: C#
public override 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, if you have not done so yet
/*
connect scott/tiger@oracle
DROP TABLE MyTable;
*/
// C#
using System;
using System.Data;
using Oracle.DataAccess.Client;
class CommitSample
{
static void Main()
{
// Drop & Create MyTable as indicated in Database Setup, at beginning
// 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.
// 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);
myTableCount = int.Parse(cmd.ExecuteScalar().ToString());
txn.Dispose();
cmd.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
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-3
■ OracleTransaction Class
■ OracleTransaction Members
Rollback()
This method rolls back a database transaction.
Declaration
// ADO.NET 2.0: C#
public override 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, if you have not done so yet.
/*
connect scott/tiger@oracle
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 previously 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
// Start a transaction
OracleTransaction txn = con.BeginTransaction(
IsolationLevel.ReadCommitted);
txn.Dispose();
cmd.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
Rollback(string)
This method rolls back a database transaction to a savepoint within the current
transaction.
Declaration
// ADO.NET 2.0: C#
public override 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.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
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, if you have not done so yet.
/*
connect scott/tiger@oracle
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 in Database Setup, at beginning
// Start a transaction
OracleTransaction txn = con.BeginTransaction(
IsolationLevel.ReadCommitted);
// Create a savepoint
txn.Save("MySavePoint");
txn.Dispose();
cmd.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleTransaction Class
■ OracleTransaction Members
OracleCollectionType Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleParameter Class" on page 5-246
■ "CollectionType" on page 5-265
OracleDBShutdownMode Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleConnection Class" on page 5-64
■ "Shutdown" on page 5-143
OracleDBStartupMode Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleConnection Class" on page 5-64
■ "Startup" on page 5-147
OracleDbType Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleParameter Class" on page 5-246
■ "OracleParameterCollection Class" on page 5-281
■ OracleParameter "OracleDbType" on page 5-268
OracleParameterStatus Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleParameter Class" on page 5-246
■ OracleParameter "ArrayBindStatus" on page 5-264
■ OracleParameter "Value" on page 5-275
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 6–1 lists all the OracleXmlCommandType enumeration values with a
description of each enumerated value.
OracleXmlQueryProperties Class
Class Inheritance
System.Object
System.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 System.IO;
using System.Data;
using System.Xml;
using System.Text;
using Oracle.DataAccess.Client;
class OracleXmlQueryPropertiesSample
{
static void Main()
{
int rows = 0;
StreamReader sr = null;
" </xsl:template>\n" +
" <xsl:template match=\"ROWSET\">\n" +
" <xsl:apply-templates select=\"ROW\"/>\n" +
" </xsl:template>\n" +
" <xsl:template match=\"ROW\">\n" +
" <EMPLOYEE>\n" +
" <EMPLOYEE_ID>\n" +
" <xsl:apply-templates select=\"EMPNO\"/>\n" +
" </EMPLOYEE_ID>\n" +
" <EMPLOYEE_NAME>\n" +
" <xsl:apply-templates select=\"ENAME\"/>\n" +
" </EMPLOYEE_NAME>\n" +
" <HIRE_DATE>\n" +
" <xsl:apply-templates select=\"HIREDATE\"/>\n" +
" </HIRE_DATE>\n" +
" <JOB_TITLE>\n" +
" <xsl:apply-templates select=\"JOB\"/>\n" +
" </JOB_TITLE>\n" +
" </EMPLOYEE>\n" +
" </xsl:template>\n" +
"</xsl:stylesheet>\n";
// Set the date, and timestamp formats for Oracle 9i Release 2, or later.
// This is just needed for queries.
if (!con.ServerVersion.StartsWith("9.0") &&
!con.ServerVersion.StartsWith("8.1"))
{
OracleGlobalization sessionParams = con.GetSessionInfo();
sessionParams.DateFormat = "YYYY-MM-DD\"T\"HH24:MI:SS";
sessionParams.TimeStampFormat = "YYYY-MM-DD\"T\"HH24:MI:SS.FF3";
sessionParams.TimeStampTZFormat = "YYYY-MM-DD\"T\"HH24:MI:SS.FF3";
con.SetSessionInfo(sessionParams);
}
cmd.XmlQueryProperties.Xslt = xslstr;
// Change the SQL query, and set the maximum number of rows to 2.
cmd.CommandText = "select * from emp e";
cmd.Parameters.Clear();
cmd.XmlQueryProperties.MaxRows = 2;
// Clean up.
cmd.Dispose();
con.Close();
con.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Members
■ OracleXmlQueryProperties Constructor
■ OracleXmlQueryProperties Properties
■ OracleXmlQueryProperties Public Methods
OracleXmlQueryProperties Members
OracleXmlQueryProperties Constructors
The OracleXmlQueryProperties constructors are listed in Table 6–2.
OracleXmlQueryProperties Properties
The OracleXmlQueryProperties properties are listed in Table 6–3.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Class
OracleXmlQueryProperties Constructor
Declaration
// C#
public OracleXmlQueryProperties();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Class
■ OracleXmlQueryProperties Members
OracleXmlQueryProperties Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Class
■ OracleXmlQueryProperties Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Class
■ OracleXmlQueryProperties Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Class
■ OracleXmlQueryProperties Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Class
■ OracleXmlQueryProperties Members
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 value is null.
The XSL document is used for XML transformation of the XML document generated
from the result set of the query.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Class
■ OracleXmlQueryProperties Members
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-3
■ OracleXmlQueryProperties Class
■ OracleXmlQueryProperties Members
Clone
This method creates a copy of an OracleXmlQueryProperties object.
Declaration
// C#
public object Clone();
Return Value
An OracleXmlQueryProperties object
Implements
ICloneable
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlQueryProperties Class
■ OracleXmlQueryProperties Members
OracleXmlSaveProperties Class
Class Inheritance
System.Object
System.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#
/* -- If HR account is being locked, you need to log on as a DBA
-- to unlock the account first. Unlock a locked users account:
using System;
using Oracle.DataAccess.Client;
class OracleXmlSavePropertiesSample
{
static void Main()
{
string[] KeyColumnsList = null;
string[] UpdateColumnsList = null;
int rows = 0;
// Do the inserts.
rows = cmd.ExecuteNonQuery();
Console.WriteLine("rows: " + rows);
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);
// 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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlSaveProperties Members
■ OracleXmlSaveProperties Constructor
■ OracleXmlSaveProperties Properties
■ OracleXmlSaveProperties Public Methods
OracleXmlSaveProperties Members
OracleXmlSaveProperties Constructor
OracleXmlSaveProperties constructors are listed in Table 6–7
OracleXmlSaveProperties Properties
The OracleXmlSaveProperties properties are listed in Table 6–8.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
OracleXmlSaveProperties Constructor
Declaration
// C#
public OracleXmlSaveProperties;
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
OracleXmlSaveProperties Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
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-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
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-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
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-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
Clone
This method creates a copy of an OracleXmlSaveProperties object.
Declaration
// C#
public object Clone();
Return Value
An OracleXmlSaveProperties object
Implements
ICloneable
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleXmlSaveProperties Class
■ OracleXmlSaveProperties Members
OracleXmlStream Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.Stream
System.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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Members
■ OracleXmlStream Constructor
■ OracleXmlStream Static Methods
■ OracleXmlStream Instance Properties
■ OracleXmlStream Instance Methods
OracleXmlStream Members
OracleXmlStream Constructors
The OracleXmlStream constructors are listed in Table 6–12.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
OracleXmlStream Constructor
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-9
■ OracleXmlStream Class
■ OracleXmlStream Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
CanRead
Overrides Stream
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
CanSeek
Overrides Stream
This property indicates whether or not forward and backward seek operation can be
performed.
Declaration
// C#
Property Value
If forward and backward seek operations can be performed, this property returns
true. Otherwise, returns false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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.
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-9
■ OracleXmlStream Class
■ OracleXmlStream Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
Clone
This method creates a copy of an OracleXmlStream object.
Declaration
// C#
public object Clone();
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
Close
Overrides Stream
This 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-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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.
The XML data is read starting from the position specified by the Position property.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlStream Class
■ OracleXmlStream Members
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 or not 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-9
■ OracleXmlStream Class
■ OracleXmlStream Members
OracleXmlType Class
Class Inheritance
System.Object
System.OracleXmlType
Declaration
// C#
public sealed class OracleXmlType : IDisposable, INullable
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Members
■ OracleXmlType Constructors
■ OracleXmlType Static Methods
■ OracleXmlType Instance Properties
■ OracleXmlType Instance Methods
OracleXmlType Members
OracleXmlType Constructors
The OracleXmlType constructors are listed in Table 6–19.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
OracleXmlType Constructors
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
■ 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
Schema
This property represents the XML schema for the XML data contained in the
OracleXmlType.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
Value
This property returns the XML data starting from the first character in the current
instance as a string.
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-9
■ OracleXmlType Class
■ OracleXmlType Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
Clone
This method creates a copy of this OracleXmlType instance.
Declaration
// C#
public object Clone();
Implements
ICloneable
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
Dispose
This method releases the resources allocated by this object.
Declaration
// C#
public void Dispose();
Implements
IDisposable
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
GetXmlDocument
This public method returns a XmlDocument object containing the XML data stored in
this OracleXmlType instance.
Declaration
// C#
public XmlDocument GetXmlDocument();
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
IsExists
IsExists checks for the existence of a particular set of nodes identified by the XPath
expression in the XML data.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleXmlType Class
■ OracleXmlType Members
Declaration
// C#
public void Update(string xpathExpr, string nsMap, OracleXmlType 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.
■ 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-9
■ OracleXmlType Class
■ OracleXmlType Members
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-9
■ OracleXmlType Class
■ OracleXmlType Members
Validate
This methods validates whether or not 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-9
■ OracleXmlType Class
■ OracleXmlType Members
This chapter describes the following Oracle Data Provider for .NET classes that
support the ADO.NET 2.0 specification.
■ OracleClientFactory Class
■ OracleConnectionStringBuilder Class
■ OracleDataSourceEnumerator Class
OracleClientFactory Class
Class Inheritance
System.Object
System.Data.Common.DbProviderFactory
Oracle.DataAccess.Client.OracleClientFactory
Declaration
// C#
public sealed class OracleClientFactory : DbProviderFactory
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 System.Data.Common;
using Oracle.DataAccess.Client;
class FactorySample
{
static void Main()
{
string constr = "user id=scott;password=tiger;data source=oracle";
DbProviderFactory factory =
DbProviderFactories.GetFactory("Oracle.DataAccess.Client");
try
{
conn.ConnectionString = constr;
conn.Open();
Console.WriteLine(ex.Message);
Console.WriteLine(ex.StackTrace);
}
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Members
■ OracleClientFactory Public Properties
■ OracleClientFactory Public Methods
OracleClientFactory Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
CanCreateDataSourceEnumerator
This property indicates whether or not the CreateDataSourceEnumerator method
is supported.
Declaration
// C#
public override bool CanCreateDataSourceEnumerator { get; }
Property Value
Returns true.
Remarks
ODP.NET supports the OracleDataSourceEnumerator object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
CreateCommand
This method returns a DbCommand object that represents an OracleCommand object.
Declaration
// C#
public override DbCommand CreateCommand();
Return Value
A DbCommand object that represents an OracleCommand object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
CreateCommandBuilder
This method returns a DbCommandBuilder object that represents an
OracleCommandBuilder object.
Declaration
// C#
public override DbCommandBuilder CreateCommandBuilder();
Return Value
A DbCommandBuilder object that represents an OracleCommandBuilder object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
CreateConnection
This method returns a DbConnection object that represents an OracleConnection
object.
Declaration
// C#
public override DbConnection CreateConnection();
Return Value
A DbConnection object that represents an OracleConnection object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
CreateConnectionStringBuilder
This method returns a DbConnectionStringBuilder object that represents an
OracleConnectionStringBuilder object.
Declaration
// C#
public override DbConnectionStringBuilder CreateConnectionStringBuilder();
Return Value
A DbConnectionStringBuilder object that represents an
OracleConnectionStringBuilder object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
CreateDataAdapter
This method returns a DbDataAdapter object that represents an
OracleDataAdapter object.
Declaration
// C#
public override DbDataAdapter CreateDataAdapter();
Return Value
A DbDataAdapter object that represents an OracleDataAdapter object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
CreateDataSourceEnumerator
This method returns a DbDataSourceEnumerator object that represents an
OracleDataSourceEnumerator object.
Declaration
// C#
public override DbDataSourceEnumerator CreateDataSourceEnumerator();
Return Value
A DbDataSourceEnumerator object that represents an
OracleDataSourceEnumerator object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
■ "OracleDataSourceEnumerator Class" on page 7-36
CreateParameter
This method returns a DbParameter object that represents an OracleParameter
object.
Declaration
// C#
public override DbParameter CreateParameter();
Return Value
A DbParameter object that represents an OracleParameter object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
CreatePermission
This method returns a CodeAccessPermission object that represents an
OraclePermission object.
Declaration
// C#
public override System.Security.CodeAccessPermission CreatePermission(
System.Security.Permissions.PermissionState state);
Parameter
■ state
A PermissionState object.
Return Value
A CodeAccessPermission object that represents an OraclePermission object.
Remarks
This method enables users, writing provider-independent code, to get a
CodeAccessPermission instance that represents an OraclePermission object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleClientFactory Class
■ OracleClientFactory Members
OracleConnectionStringBuilder Class
Class Inheritance
System.Object
System.Data.Common.DbConnectionStringBuilder
Oracle.DataAccess.Client.OracleConnectionStringBuilder
Declaration
// C#
public sealed class OracleConnectionStringBuilder : DbConnectionStringBuilder
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
The following rules must be followed for setting values with reserved characters:
1. Values containing characters enclosed within single quotes
If the value contains characters that are enclosed within single quotation marks,
then the entire value must be enclosed within double quotation marks.
For example, password = "'scoTT'" where the value is 'scoTT'.
2. Values containing characters enclosed within double quotes
Values should be enclosed in double quotation marks to preserve the case and to
avoid the upper casing of values.
If the value contains characters enclosed in double quotation marks, then it must
be enclosed in single quotation marks.
For example, password = '"scoTT"' where the value is "scoTT".
3. Values containing characters enclosed in both single and double quotes
If the value contains characters enclosed in both single and double quotation
marks, the quotation mark used to enclose the value must be doubled each time it
occurs within the value.
For example, password = '"sco''TT"' where the value is "sco'TT".
4. Values containing spaces
All leading and trailing spaces are ignored, but the spaces between the value are
recognized. If the value needs to have leading or trailing spaces then it must be
enclosed in double quotation marks.
For example, User ID = Sco TT where the value is <Sco TT>.
For example, User ID = "Sco TT " where the value is <Sco TT>.
Example
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
using System.Collections;
class ConnectionStringBuilderSample
{
static void Main(string[] args)
{
string connString = "user id=scott;password=tiger;Data source=oracle;";
bool bRet = false;
//returns false
connStrBuilder.ContainsKey("Invalid");
while (keys.MoveNext())
{
values.MoveNext();
Console.WriteLine("Key: {0} Value: {1} \n"
,keys.Current ,values.Current);
}
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Members
■ OracleConnectionStringBuilder Constructors
■ OracleConnectionStringBuilder Public Properties
■ OracleConnectionStringBuilder Public Methods
OracleConnectionStringBuilder Members
OracleConnectionStringBuilder Constructors
OracleConnectionStringBuilder constructors are listed in Table 7–5.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
OracleConnectionStringBuilder Constructors
Overload List:
■ OracleConnectionStringBuilder()
This constructor instantiates a new instance of
OracleConnectionStringBuilder class.
■ OracleConnectionStringBuilder(string)
This constructor instantiates a new instance of the
OracleConnectionStringBuilder class with the provided connection string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
OracleConnectionStringBuilder()
This constructor instantiates a new instance of the
OracleConnectionStringBuilder class.
Declaration
// C#
public OracleConnectionStringBuilder();
Remarks
The ConnectionString property is empty after the object is created.
OracleConnectionStringBuilder(string)
This constructor instantiates a new instance of the
OracleConnectionStringBuilder class with the provided connection string.
Declaration
// C#
public OracleConnectionStringBuilder(string connectionString);
Parameters
■ connectionString
The connection information.
Exceptions
ArgumentNullException - The connectionString parameter is null.
ArgumentException - The connectionString parameter is invalid.
Remarks
The ConnectionString property of this instance is set to the supplied connection
string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
ConnectionLifetime
This property specifies the value corresponding to the Connection Lifetime
attribute in the ConnectionString property.
Declaration
// C#
public int ConnectionLifetime{get; set;}
Property Value
An int that represents the value of the supplied attribute.
Exceptions
OracleException - The specified value is less than zero.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
ConnectionTimeout
This property specifies the value corresponding to the Connection Timeout
attribute in the ConnectionString property.
Declaration
// C#
public int ConnectionTimeout{get; set;}
Property Value
An int that represents the value of the supplied attribute.
Exceptions
OracleException - The specified value is less than zero.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
ContextConnection
This property specifies the value corresponding to the Context Connection
attribute in the ConnectionString property.
Declaration
// C#
public bool ContextConnection {get; set;}
Property Value
A bool that represents the value of the supplied attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
DataSource
This property specifies the value corresponding to the Data Source attribute in the
ConnectionString property.
Declaration
// C#
public string DataSource{get; set;}
Property Value
A string that represents the value of the supplied attribute.
Exceptions
ArgumentNullException - The specified value is null.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
DBAPrivilege
This property specifies the value corresponding to the DBA Privilege attribute in the
ConnectionString property.
Declaration
// C#
public string DBAPrivilege{get; set;}
Property Value
A string that represents the value of the supplied attribute.
Possible values are SYSDBA or SYSOPER.
Exceptions
ArgumentNullException - The specified value is null.
OracleException - The specified value is invalid.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
DecrPoolSize
This property specifies the value corresponding to the Decr Pool Size attribute in
the ConnectionString property.
Declaration
// C#
public int DecrPoolSize{get; set;}
Property Value
An int that represents the value of the supplied attribute.
Exceptions
OracleException - The specified value is less than 1.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
Enlist
This property specifies the value corresponding to the Enlist attribute in the
ConnectionString property.
Declaration
// C#
public string Enlist{get; set;};
Property Value
A string that represents the value of the supplied attribute. Values are case-insensitive.
Possible values are: dynamic, true, false, yes, and no.
Exceptions
ArgumentNullException - The specified value is null.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
HAEvents
This property specifies the value corresponding to the HA Events attribute in the
ConnectionString property.
Declaration
// C#
public bool HAEvents{get; set;}
Property Value
A bool that represents the value of the supplied attribute.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
IncrPoolSize
This property specifies the value corresponding to the Incr Pool Size attribute in
the ConnectionString property.
Declaration
// C#
public int IncrPoolSize{get; set;}
Property Value
An int that represents the value of the supplied attribute.
Exceptions
OracleException - The specified value is less than 1.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
IsFixedSize
Indicates whether or not the Connection String Builder has a fixed size.
Declaration
// C#
public override bool IsFixedSize{get;}
Property Value
Returns true if the Connection String Builder has a fixed size; otherwise, returns
false.
Remarks
Attributes cannot be added or removed. They can only be modified for connection
strings with a fixed size.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
Item
This property specifies the value associated with the specified attribute.
Declaration
// C#
public override object this[string keyword]{get; set;}
Property Value
An object value corresponding to the attribute.
Exceptions
ArgumentNullException - The specified attribute is null.
OracleException - The specified attribute is not supported or the specified value is
invalid.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
Keys
This property specifies a collection of attributes contained in the Connection String
Builder.
Declaration
// C#
public override ICollection Keys{get;}
Property Value
Returns an ICollection that represents the attributes in the Connection String
Builder.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
LoadBalancing
This property specifies the value corresponding to the Load Balancing attribute in
the ConnectionString property.
Declaration
// C#
public bool LoadBalancing {get; set;}
Property Value
A bool that contains the value of the supplied attribute.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
MaxPoolSize
This property specifies the value corresponding to the Max Pool Size attribute in the
ConnectionString property.
Declaration
// C#
public int MaxPoolSize{get; set;}
Property Value
An int that represents the value of the supplied attribute.
Exceptions
OracleException - The specified value is less than 1.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
MetadataPooling
This property specifies the value that corresponds to the Metadata Pooling attribute
in the ConnectionString property.
Declaration
// C#
public bool MetadataPooling{get; set;};
Property Value
A bool containing the value of the supplied attribute.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
MinPoolSize
This property specifies the value corresponding to the Min Pool Size attribute in the
ConnectionString property.
Declaration
// C#
public int MinPoolSize{get; set;}
Property Value
An int that contains the value of the supplied attribute.
Exceptions
OracleException - The specified value is less than 0.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
Password
This property specifies the value corresponding to the Password attribute in the
ConnectionString property.
Declaration
// C#
public string Password{get; set;}
Property Value
A string that contains the value of the supplied attribute.
Exception
ArgumentNullException - The specified value is null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
PersistSecurityInfo
This property specifies the value corresponding to the Persist Security Info
attribute in the ConnectionString property.
Declaration
// C#
public bool PersistSecurityInfo{get; set;}
Property Value
A bool that represents the value of the supplied attribute.
Remarks
When an OracleConnectionStringBuilder instance is created, this property gets
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
Pooling
This property specifies the value corresponding to the Pooling attribute in the
ConnectionString property.
Declaration
// C#
public bool Pooling {get; set;}
Property Value
A bool that represents the value of the supplied attribute.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
ProxyPassword
This property specifies the value corresponding to the Proxy Password attribute in
the ConnectionString property.
Declaration
// C#
public string ProxyPassword {get; set;}
Property Value
A string that represents the value of the supplied attribute.
Exception
ArgumentNullException - The specified value is null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
ProxyUserId
This property specifies the value corresponding to the Proxy User Id attribute in the
ConnectionString property.
Declaration
// C#
public string ProxyUserId {get; set;}
Property Value
A string that represents the value of the supplied attribute.
Exception
ArgumentNullException - The specified value is null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
SelfTuning
This property specifies the value corresponding to the Self Tuning attribute in the
ConnectionString property.
Declaration
// C#
public bool SelfTuning {get; set;}
Property Value
A bool that represents the value of the supplied attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
StatementCachePurge
This property specifies the value corresponding to the Statement Cache Purge
attribute in the ConnectionString property.
Declaration
// C#
Property Value
A bool that represents the value of the supplied attribute.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
StatementCacheSize
This property specifies the value corresponding to the Statement Cache Size
attribute in the ConnectionString property.
Declaration
// C#
public int StatementCacheSize{get; set;}
Property Value
An int that represents the value of the supplied attribute.
Exceptions
OracleException - The specified value is less than zero.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
UserID
This property specifies the value corresponding to the User Id attribute in the
ConnectionString property.
Declaration
// C#
public string UserID{get; set;}
Property Value
A string that represents the value of the supplied attribute.
Exception
ArgumentNullException - The specified value is null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
ValidateConnection
This property specifies the value corresponding to the Validate Connection
attribute in the ConnectionString property.
Declaration
// C#
public bool ValidateConnection{get; set;}
Property Value
A bool that represents the value of the supplied attribute.
Remarks
When an OracleConnectionStringBuilder instance is created, this property is
set to the default value of the corresponding connection string attribute.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
Values
This property specifies a collection of values contained in the Connection String
Builder.
Declaration
// C#
public override ICollection Values{get;}
Property Value
Returns an ICollection that represents the values in the Connection String Builder.
Remarks
The order of the values in the ICollection is unspecified, but is the same as the
associated attributes in the ICollection returned by the Keys property.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
Clear
This method clears the connection string contents.
Declaration
// C#
public override void Clear();
Remarks
All key/value pairs are removed from the OracleConnectionStringBuilder
object and the ConnectionString property is set to Empty.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
ContainsKey
This method indicates whether or not a specific attribute in the connection string is
supported by ODP.NET.
Declaration
// C#
public override bool ContainsKey(string keyword);
Parameters
■ keyword
The attribute being verified.
Return Value
Returns true if the specified attribute exists; otherwise, returns false.
Exceptions
ArgumentNullException - The specified attribute is null.
Remarks
This method indicates if the attribute is part of the provider-supported attributes. It
does not indicate if the user added the attribute to the connection string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
Remove
This method removes the entry corresponding to the specified attribute from the
connection string.
Declaration
// C#
public override bool Remove(string keyword);
Parameters
■ keyword
The attribute that specifies the entry to be removed.
Return Value
Returns true if the attribute existed in the connection string and the corresponding
entry was removed; otherwise, returns false.
Exceptions
ArgumentNullException - The specified attribute is null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
TryGetValue
This method returns the value corresponding to the supplied attribute, as an output
parameter.
Declaration
// C#
public override bool TryGetValue(string keyword, out object value);
Parameters
■ keyword
The attribute for which the value is being retrieved.
■ value
The value of the supplied attribute.
Sets value to the default value if the attribute is not present in the connection
string.
Return Value
Returns true if the value that corresponds to the attribute has been successfully
retrieved; otherwise, returns false. If the attribute is not present in the connection
string, returns false and sets the value to null.
Exceptions
ArgumentNullException - The specified attribute is null.
Remarks
If the function returns false, sets value to null.
If the attribute is not present in the connection string, sets value to the default value.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleConnectionStringBuilder Class
■ OracleConnectionStringBuilder Members
OracleDataSourceEnumerator Class
Class Inheritance
System.Object
System.DbDataSourceEnumerator
Oracle.DataAccess.Client.OracleDataSourceEnumerator
Declaration
// C#
public sealed class OracleDataSourceEnumerator : DbDataSourceEnumerator
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 System.Data.Common;
using Oracle.DataAccess.Client;
class DataSourceEnumSample
{
static void Main()
{
string ProviderName = "Oracle.DataAccess.Client";
if (factory.CanCreateDataSourceEnumerator)
{
DbDataSourceEnumerator dsenum = factory.CreateDataSourceEnumerator();
DataTable dt = dsenum.GetDataSources();
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataSourceEnumerator Members
■ OracleDataSourceEnumerator Public Methods
OracleDataSourceEnumerator Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataSourceEnumerator Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataSourceEnumerator Class
■ OracleDataSourceEnumerator Members
GetDataSources
This method returns a DataTable object with information on all the TNS alias entries
in the tnsnames.ora file.
Declaration
// C#
public override DataTable GetDataSources();
Return Value
A DataTable object.
Remarks
This method returns a DataTable object for each TNS Alias entry that exists in the
tnsnames.ora file.
If the tnsnames.ora file is not found, then the returned DataTable object is empty.
The following columns are returned for each row, but only the InstanceName
column is populated.
■ InstanceName (type: System.String)
■ ServerName (type: System.String)
■ ServiceName (type: System.String)
■ Protocol (type: System.String)
■ Port (type: System.String)
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDataSourceEnumerator Class
■ OracleDataSourceEnumerator Members
This chapter describes the following ODP.NET HA event class and enumerations:
■ OracleHAEventArgs Class
■ OracleHAEventHandler Delegate
■ OracleHAEventSource Enumeration
■ OracleHAEventStatus Enumeration
OracleHAEventArgs Class
Class Inheritance
System.Object
System.EventArgs
Oracle.DataAccess.Client.OracleHAEventArgs
Declaration
// C#
public sealed class OracleHAEventArgs
Thread Safety
All public methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
When any HA event occurs for a service, service member, host, node, or instance that
an OracleConnection object is set to with "ha events=true", the
OracleConnection.HAEvent is triggered and passes an instance of
OracleHAEventArgs to all the delegates that have registered with the event.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version 2.0 or later.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Members
■ OracleHAEventArgs Properties
■ "OracleConnection Class" on page 5-64
■ "HAEvent" on page 5-111
OracleHAEventArgs Members
OracleHAEventArgs Properties
The OracleHAEventArgs properties are listed in Table 8–2.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ "HAEvent" on page 5-111
OracleHAEventArgs Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
DatabaseDomainName
This property specifies the domain name of the database that is affected by the HA
event.
Declaration
// C#
public string DatabaseDomainName {get;}
Property Value
The domain name of the database that is affected by the HA Event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
■ "HAEvent" on page 5-111
DatabaseName
This property specifies the database that is affected by the HA event.
Declaration
// C#
public string DatabaseName {get;}
Property Value
This property specifies the database name that is affected by the HA event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
■ "HAEvent" on page 5-111
HostName
This property specifies the host that triggered the HA event.
Declaration
// C#
public string HostName {get;}
Property Value
The host that is affected by the HA Event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
■ "HAEvent" on page 5-111
InstanceName
This property specifies the instance that triggered the HA event.
Declaration
// C#
public string InstanceName {get;}
Property Value
The instance that is affected by the HA Event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
■ "HAEvent" on page 5-111
ServiceName
This property specifies the service that triggered the HA event.
Declaration
// C#
public string ServiceName {get;}
Property Value
The service that is affected by the HA Event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
■ "HAEvent" on page 5-111
Source
This property specifies the source that triggered the HA event.
Declaration
// C#
public OracleHAEventSource Source {get;}
Property Value
The source that triggered the HA Event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
■ "HAEvent" on page 5-111
Status
This property specifies the status of the source that triggered the HA event.
Declaration
// C#
public OracleHAEventStatus Status {get;}
Property Value
The status of the source that triggered the HA Event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
■ "HAEvent" on page 5-111
Time
This property specifies the time when the HA event was triggered on the server.
Declaration
// C#
public DateTime Time {get;}
Property Value
The time that the HA Event was triggered.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ OracleHAEventArgs Members
■ "HAEvent" on page 5-111
OracleHAEventHandler Delegate
Declaration
// C#
public delegate void OracleHAEventHandler(object sender, OracleHAEventArgs
eventArgs);
Parameters
■ sender
The source of the event.
■ EventArgs
The OracleHAEventArgs object that contains the event data.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version 2.0 or later.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ "HAEvent" on page 5-111
OracleHAEventSource Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ "Source" on page 8-6
OracleHAEventStatus Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleHAEventArgs Class
■ "Status" on page 8-6
This chapter describes Oracle Data Provider for .NET Change Notification Classes,
Event Delegates, and Enumerations, which support Continuous Query Notification.
OracleDependency Class
Class Inheritance
System.Object
Oracle.DataAccess.Client.OracleDependency
Declaration
// C#
public sealed class OracleDependency
Thread Safety
All public static methods are thread-safe, although methods do not guarantee thread
safety.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
Comment: Not supported in a .NET stored procedure
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Members
■ OracleDependency Constructors
■ OracleDependency Static Fields
■ OracleDependency Static Methods
■ OracleDependency Methods
■ OracleDependency Properties
■ OracleDependency Events
OracleDependency Members
OracleDependency Constructors
OracleDependency constructors are listed in Table 9–1.
OracleDependency Properties
OracleDependency properties are listed in Table 9–4.
OracleDependency Methods
OracleDependency methods are listed in Table 9–5.
OracleDependency Events
The OracleDependency event is listed in Table 9–6.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
OracleDependency Constructors
Overload List:
■ OracleDependency ( )
This constructor creates an instance of the OracleDependency class.
■ OracleDependency(OracleCommand)
This constructor creates an instance of the OracleDependency class and binds it
to the specified OracleCommand instance.
■ OracleDependency(OracleCommand, bool, int, bool)
This constructor creates an instance of the OracleDependency class and binds it
to the specified OracleCommand instance, specifying whether or not a notification
is to be removed upon notification, the timeout value of the notification
registration, and the persistence of the notification.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
OracleDependency ( )
This constructor creates an instance of the OracleDependency class.
Declaration
// C#
public OracleDependency ()
Remarks
Using this constructor does not bind any OracleCommand to the newly constructed
OracleDependency. Use the AddCommandDependency method to do so.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
OracleDependency(OracleCommand)
This constructor creates an instance of the OracleDependency class and binds it to
an OracleCommand instance.
Declaration
// C#
public OracleDependency (OracleCommand cmd)
Parameters
■ cmd
The command that the OracleDependecy object binds to.
Exceptions
ArgumentNullException - The cmd parameter is null.
InvalidOperationException - The specified OracleCommand instance already
contains a notification request.
Remarks
When this OracleDependency constructor binds the OracleCommand instance to an
OracleDependency instance, it causes the creation of an
OracleNotificationRequest instance and then sets that
OracleNotificationRequest instance to the OracleCommand.Notification
property.
The Continuous Query Notification is registered with the database, when the
command is executed. Any of the command execution methods (for example,
ExecuteNonQuery, ExecuteReader, and so on) will register the notification
request. An OracleDependency may be bound to more than one OracleCommand.
When one of these OracleCommand object statements is executed, the statement is
registered with the associated OracleCommand. Although the registration happens on
each OracleCommand separately, one OracleDependency can be responsible for
detecting and sending notifications that occur for all OracleCommand objects that the
OracleDependency is associated with. The OnChangeEventArgs that is passed to
the application for the OnChange event provides information on what has changed in
the database.
The OracleNotificationRequest instance that is created by this constructor has
the following default property values:
■ IsNotifiedOnce is set to the value True.
■ Timeout is set to 50,000 seconds.
■ IsPersistent is set to the value False, that is, the invalidation message is not
persistent, but is stored in an in-memory queue before delivery.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
Declaration
// C#
public OracleDependency (OracleCommand cmd, bool isNotifiedOnce, long timeout,
bool isPersistent)
Parameters
■ cmd
The command associated with the Continuous Query Notification request.
■ isNotifiedOnce
An indicator that specifies whether or not the registration is removed
automatically once the notification occurs.
■ timeout
The amount of time, in seconds, that the registration stays active. When timeout
is set to 0, the registration never expires. The valid values for timeout are
between 0 and 4294967295.
■ isPersistent
Indicates whether or not the invalidation message should be queued persistently
in the database before delivery. If the isPersistent parameter is set to True,
the message is queued persistently in the database and cannot be lost upon
database failures or shutdowns. If the isPersistent property is set to False,
the message is stored in an in-memory queue before delivery and might be lost.
Database performance is faster if the message is stored in an in-memory queue
rather than in the database queue.
Exceptions
ArgumentNullException - The cmd parameter is null.
ArgumentOutOfRangeException - The specified timeout is invalid.
InvalidOperationException - The specified OracleCommand instance already
contains a notification request.
Remarks
When this OracleDependency constructor binds the OracleCommand instance to an
OracleDependency instance, it causes the creation of an
OracleNotificationRequest instance and then sets that
OracleNotificationRequest instance to the OracleCommand.Notification
property.
The Continuous Query Notification is registered with the database, when the
command is executed. Any of the command execution methods (for example,
ExecuteNonQuery, ExecuteReader, and so on) will register the notification
request. An OracleDependency may be bound to more than one OracleCommand.
When one of these OracleCommand object statements is executed, the statement is
registered with the associated OracleCommand. Although the registration happens on
each OracleCommand separately, one OracleDependency can be responsible for
detecting and sending notifications that occur for all OracleCommand objects that the
OracleDependency is associated with. The OnChangeEventArgs that is passed to
the application for the OnChange event provides information on what has changed in
the database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
Port
This static field indicates the port number that the notification listener listens on, for
database notifications.
Declaration
// C#
public static int Port{get; set}
Property Value
An int value that represents the number of the port that listens for the database
notifications. If the port number is set to -1, a random port number is assigned for the
listener when the listener is started. Otherwise, the specified port number is used to
start the listener.
Exceptions
ArgumentOutOfRangeException - The port number is set to a negative value.
InvalidOperationException - The port number is being changed after the
listener has started.
Remarks
The port number specified by the OracleDependency.Port static field is used by
the notification listener that runs within the same application domain as ODP.NET.
This port number receives Continuous Query Notifications from the database. One
notification listener is capable of listening to all Continuous Query Notifications and
therefore, only one notification listener is created for each application domain.
The notification listener is created when a command associated with an
OracleDependency object is executed for the first time during the application
domain lifetime. The port number specified for the OracleDependency.Port static
field is used by the listener for its lifetime. The OracleDependency.Port static field
can be changed after the creation of the notification listener, but doing so does not
affect the actual port number that the notification listener listens on.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
GetOracleDependency
This static method returns an OracleDependency instance based on the specified
unique identifier.
Declaration
// C#
public static OracleDependency GetOracleDependency(string guid)
Parameters
■ guid
The string representation of the unique identifier of an OracleDependency
instance.
Exceptions
ArgumentException - The specified unique identifier cannot locate an
OracleDependency instance.
Return Value
An OracleDependency instance that has the specified guid parameter.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
OracleDependency Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
DataSource
This property indicates the data source associated with the OracleDependency
instance.
Declaration
// C#
public string DataSource{get;}
Property Value
A string that indicates the data source associated with the OracleDependency
instance.
Remarks
The DataSource property is populated with the data source once the
OracleCommand associated with the OracleDependency executes and registers for
the notification successfully.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
HasChanges
This property indicates whether or not there is any change in the database associated
with this dependency.
Declaration
// C#
public bool HasChanges{get;}
Property Value
A bool value that returns True if the database has detected changes that are
associated with this dependency; otherwise, returns False.
Remarks
As an alternative to using the OnChange event, applications can check the
HasChanges property to determine if there are any changes in the database associated
with this dependency.
Once the HasChanges property is accessed, its value is reset to False so that the next
notification can then be acknowledged.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
Id
This property represents the unique identifier for the OracleDependency instance.
Declaration
// C#
public string Id{get;}
Property Value
A string that represents the unique identifier that was generated for the
OracleDependency instance when it was created.
Remarks
This property is set when the OracleDependency instance is created.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
IsEnabled
This property specifies whether or not the dependency is enabled between the
application and the database.
Declaration
// C#
public bool IsEnabled {get;}
Property Value
A bool value that specifies whether or not dependency is enabled between the
application and the database.
Remarks
The dependency between the application and the database is not established when the
OracleDependency instance is created. The dependency is established when the
command that is associated with this dependency is executed, at which time the
notification request is registered with the database. The dependency ends when the
notification registration is removed from the database or when it times out.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
QueryBasedNotification
This instance property specifies whether the change notification registration is
object-based or query-based.
Declaration
// C#
public bool QueryBasedNotification{get; set;}
Property Value
Specifies whether the change notification registration is object-based or not.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
This property value will be ignored if it is set after the command execution that
registers the command for change notification.
By default, this property is true.
ODP.NET developers can register their queries on the row level, not just the object
level, beginning with Oracle Data Provider for .NET release 11.1 and Oracle Database
11g release 1 (11.1). The application only receives notification when the selected row or
rows change. Query-based notifications provide developers more granularity for using
client-side cached data, as they can be more specific about what changes the
application needs to be notified of.
OracleNotificationType enumeration is set to Query for query-based
notifications.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
RegisteredQueryIDs
This instance property provides a list of CHANGE_NOTIFICATION_QUERY_IDs.
Declaration
// C#
public ArrayList RegisteredQueryIDs {get;}
Property Value
This property is an ArrayList of CHANGE_NOTIFICATION_QUERY_IDs.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
This property provides a list of CHANGE_NOTIFICATION_QUERY_IDs that uniquely
identify the query that has been registered for change notification. The notification
returned from the database will also contain these IDs, allowing applications to
determine the query that the notifications are for.
The QueryId at index n in RegisteredQueryIDs is for the statement at index n the
RegisteredResources at index n.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
RegisteredResources
This property indicates the database resources that are registered in the notification
registration.
Declaration
// C#
public ArrayList RegisteredResources{get;}
Property Value
The registered resources in the notification registration.
Remarks
The ArrayList contains all the command statement or statements that are registered
for notification through this OracleDependency object. It is appropriately updated
when the Continuous Query Notification is registered by a command execution.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
RowidInfo
This property specifies whether or not ROWID information is part of change
notification events fired whenever data changes on the database.
Declaration
// C#
public OracleRowidInfo RowidInfo {get; set;};
Property Value
An OracleRowidInfo enumeration type that determines the inclusion of ROWID in
the change notification event.
Remarks
There are three OracleRowidInfo enumeration types that are valid for this property:
■ Default includes ROWID information in the change notification event only if
OracleCommand.AddRowid property is set to true or if ROWID is in the select list
of the query that is registered for change notification.
■ Include includes ROWID information regardless of whether or not ROWID is in
the select-list for the query.
■ Exclude excludes ROWID information regardless of whether or not ROWID is in
the select-list.
For change notification registrations that involve stored procedure executions, change
notification events related to the REF CURSOR contain ROWID information only if
RowidInfo property is set to OracleRowidInfo.Include.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
■ "OracleRowidInfo Enumeration" on page 9-41
UserName
This property indicates the database user name associated with the
OracleDependency instance.
Declaration
// C#
public string UserName{get;}
Property Value
A string that indicates the database user name associated with the
OracleDependency instance. This database user registers the Continuous Query
Notification request with the database.
Remarks
The UserName property is populated with the user name once the OracleCommand
associated with the OracleDependency executes and registers for the notification
successfully. Only the database user who creates the notification registration, or the
database system administrator, can remove the registration.
The user specified by this property must have the CHANGE NOTIFICATION privilege
to register successfully for the Continuous Query Notification with the database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
OracleDependency Methods
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
AddCommandDependency
This instance method binds the OracleDependency instance to the specified
OracleCommand instance.
Declaration
// C#
Public void AddCommandDependency (OracleCommand cmd);
Parameters
■ cmd
The command that is to be bound to the OracleDependency object.
Exceptions
ArgumentNullException - The cmd parameter is null.
InvalidOperationException - The specified OracleCommand instance already
contains a notification request.
Remarks
An OracleDependency instance can bind to multiple OracleCommand instances.
While it binds an existing OracleDependency instance to an OracleCommand
instance, the AddCommandDependency method creates an
OracleNotificationRequest instance, and sets it to the specified
OracleCommand.Notification property.
When this method creates an OracleNotificationRequest instance, the following
OracleNotificationRequest properties are set:
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
■ "OracleDependency(OracleCommand)" on page 9-5 for
OracleNotificationRequest property value
RemoveRegistration
This instance method removes the specified dependency between the application and
the database. Once the registration of the dependency is removed from the database,
the OracleDependency is no longer able to detect any changes that the database
undergoes.
Declaration
// C#
public void RemoveRegistration(OracleConnection con)
Parameters
■ con
The connection associated with the OracleDependency instance.
Exceptions
InvalidOperationException - The associated connection is not open.
Remarks
The notification registration associated with the OracleDependency instance is
removed from the database.
The OracleConnection parameter must be in an opened state. This instance method
does not open the connection implicitly for the application.
An exception is thrown if the dependency is not valid.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
OracleDependency Events
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
OnChange
The OnChange event is sent when a database notification associated with the
dependency is received from the database. The information related to the notification
is stored in the OracleChangeNotificationEventArgs class.
Declaration
// C#
public event OnChangeEventHandler OnChange;
Remarks
The OnChange event occurs if any result set associated with the dependency changes.
For objects that are part of a Transaction, notifications will be received for each
modified object. This event also occurs for other actions related to database or
registration status, such as database shutdowns and startups, or registration timeouts.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleDependency Class
■ OracleDependency Members
OracleNotificationRequest Class
Class Inheritance
System.Object
Oracle.DataAccess.Client.OracleNotificationRequest
Declaration
// C#
public sealed class OracleNotificationRequest
Thread Safety
All public static methods are thread-safe, although methods do not guarantee thread
safety.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
Comment: Not supported in a .NET stored procedure
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Static Methods
■ OracleNotificationRequest Properties
■ OracleNotificationRequest Methods
OracleNotificationRequest Members
OracleNotificationRequest Properties
OracleNotificationRequest properties are listed in Table 9–13.
OracleNotificationRequest Methods
OracleNotificationRequest methods are listed in Table 9–14.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
OracleNotificationRequest Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
IsNotifiedOnce
This property indicates whether or not the registration is to be removed upon
notification.
Declaration
// C#
public bool IsNotifiedOnce{get; set;}
Property Value
A bool value that indicates whether or not the registration is to be removed upon
notification.
Remarks
The default value is false for AQ. This is different from change notification where
the default value is true.
Modifying this property after the completion of a successful registration has no effect.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
IsPersistent
This property indicates whether or not the notification message should be queued
persistently in the database until delivery.
Declaration
// C#
public bool IsPersistent{get; set;}
Property Value
A bool value that indicates whether or not the notifications should be stored
persistently in the database until delivery.
When the IsPersistent property is set to True, the message is queued persistently
in the database and cannot be lost upon database failures or shutdowns. When the
IsPersistent property is set to False, the message is stored in an in-memory
queue before delivery and could be lost.
This property does not apply to NotificationRegistration which is always
persistent.
This property only applies to the notification message after it has been sent.
Remarks
The default value is false.
The database performs faster if the message is stored in an in-memory queue rather
than a database queue.
Modifying this property after the completion of a successful registration has no effect.
This property is ignored for grouping notifications.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
Timeout
This property specifies the time, in seconds, that the registration remains alive.
Declaration
// C#
public long Timeout{get; set}
Property Value
A long value that specifies the time, in seconds, that the registration remains alive.
The valid values for the Timeout property are between 0 and 4294967295.
Exceptions
ArgumentOutOfRangeException - The specified Timeout is invalid.
Remarks
The default value is 0 (infinite) for AQ and 50000 for change notification. If the
Timeout property is set to 0, then the registration does not expire.
If the registration is removed because the Timeout value has been reached, then the
database sends a notification indicating the expiration.
Modifying this property after the completion of a successful registration has no effect.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
GroupingNotificationEnabled
This property specifies whether grouping notification is enabled or not.
Declaration
// C#
public bool GroupingNotificationEnabled {get; set}
Property Value
A true value indicates that grouping notification is enabled. A false value indicates
that grouping notification is disabled.
Remarks
The default value is false.
Modifying this property after the completion of a successful registration has no effect.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
GroupingType
This property specifies the type of grouping notification.
Declaration
// C#
public OracleAQNotificationGroupingType GroupingType {get; set}
Property Value
An OracleAQNotificationGroupingType enum value
Remarks
The default value is OracleAQNotificationGroupingType.Summary.
Modifying this property after the completion of a successful registration has no effect.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
GroupingInterval
This property specifies the interval of grouping notification in seconds. The group
notifications are delivered at intervals specified by this property.
Declaration
// C#
public int GroupingInterval {get; set}
Property Value
An integer specifying the grouping interval in seconds.
Remarks
The default value is 600 seconds.
The range of GroupingInterval is from 0 to Int32.MaxValue.
Modifying this property after the completion of a successful registration has no effect.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
OracleNotificationRequest Methods
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationRequest Members
■ OracleNotificationRequest Class
OracleNotificationEventArgs Class
Class Inheritance
System.Object
System.EventArgs
Oracle.DataAccess.Client.OracleNotificationEventArgs
Declaration
// C#
public sealed class OracleNotificationEventArgs
Thread Safety
All public static methods are thread-safe, although methods do not guarantee thread
safety.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
Comment: Not supported in a .NET stored procedure
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Members
■ OracleNotificationEventArgs Static Fields
■ OracleNotificationEventArgs Static Methods
■ OracleNotificationEventArgs Properties
■ OracleNotificationEventArgs Methods
OracleNotificationEventArgs Members
OracleNotificationEventArgs Properties
OracleNotificationEventArgs properties are listed in Table 9–20.
OracleNotificationEventArgs Methods
OracleNotificationEventArgs methods are listed in Table 9–21.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
OracleNotificationEventArgs Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
Details
This property contains detailed information about the current notification.
Declaration
// C#
Public DataTable Details{get;}
Property Value
A DataTable instance that contains detailed information about the current
notification.
Remarks
The returned DataTable object contains column data about the current notification in
order as shown in Table 9–25.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
Info
This property indicates the database events for the notification.
Declaration
// C#
public OracleNotificationInfo Info{get;}
Property Value
An OracleNotificationInfo value that indicates the database event for the
notification.
Remarks
The OracleNotificationInfo value is an enumeration type. If several events are
received from the invalidation message, the Info property is set to one of the
OracleNotificationInfo enumeration values associated with the database
events. For example, if a table has been altered and a new row has been inserted into
another table, the Info property is set to either
OracleNotificationInfo.Altered or OracleNotificationInfo.Insert.
To obtain more detailed information from the invalidation message, use the Details
and the ResourceNames properties.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
■ "Details" on page 9-34
■ "ResourceNames" on page 9-36
■ "OracleNotificationInfo Enumeration" on page 9-44
ResourceNames
This property indicates the database resources related to the current notification.
Declaration
// C#
public string[] ResourceNames{get;}
Property Value
A string array that indicates the database resources related to the current notification.
Remarks
For Continuous Query Notification, the ResourceNames property contains
information about the invalidated object names in the format <schema_
name>.<object _name>. To obtain more detailed information about the changes for
invalidated objects, use the Details property.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
■ "Details" on page 9-34
Source
This property returns the database event source for the notification.
Declaration
// C#
public OracleNotificationSource Source{get;}
Property Value
The OracleNotificationSource value for the notification.
Remarks
The OracleNotificationSource value is an enumeration type. If several event
sources are received from the notification message, the Source property is set to one
of the OracleNotificationSource enumeration values related to the database
event source. For example, if a table has been altered (by the ALTER TABLE command)
and a new row has been inserted into the same table, the Source property is set to
either OracleNotificationSource.Object or
OracleNotificationSource.Data.
For Continuous Query Notification:
■ When the Source property is set to OracleNotificationSource.Data:
– The Info property is set to one of the following:
* OracleNotificationInfo.Insert
* OracleNotificationInfo.Delete
* OracleNotificationInfo.Update
– The ResourceNames property is set, and the elements are set to the
invalidated object names.
– The Details property contains detailed information on the change of each
invalidated table.
■ When the Source property is set to OracleNotificationSource.Database:
– The Info property is set to one of the following:
* OracleNotificationInfo.Startup
* OracleNotificationInfo.Shutdown
* OracleNotificationInfo.Shutdown_Any
* OracleNotificationInfo.Dropped
■ When the Source property is set to OracleNotificationSource.Object:
– The Info property is set to either OracleNotificationInfo.Altered or
OracleNotificationInfo.Dropped.
– The ResourceNames property is set, and the array elements of the
ResourceNames property are set to the object names that have been altered
or dropped.
– The Details property contains detailed information on the changes of the
object.
■ When the Source property is set to
OracleNotificationSource.Subscription:
– The Info property is set to the following:
* OracleNotificationInfo.End
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
■ "OracleNotificationSource Enumeration" on page 9-43
Type
This property returns the database event type for the notification.
Declaration
// C#
public OracleNotificationType Type{get;}
Property Value
An OracleNotificationType enumeration value that represents the type of the
database event notification.
Remarks
The OracleNotificationType value is an enumeration type. If several event types
are received from the notification message, then the Type property is set to one of the
OracleNotificationType enumeration values related to the database event type.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
■ "OracleNotificationType Enumeration" on page 9-42
OracleNotificationEventArgs Methods
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
OnChangeEventHandler Delegate
Declaration
// C#
public delegate void OnChangeEventHandler(object sender,
OracleNotificationEventArgs args);
Parameters
■ sender
The source of the event.
■ args
The OracleNotificationEventArgs instance that contains the event data.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
Comment: Not supported in a .NET stored procedure
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleNotificationEventArgs Class
■ OracleNotificationEventArgs Members
OracleRowidInfo Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "RowidInfo" on page 9-16
OracleNotificationType Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
OracleNotificationSource Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
OracleNotificationInfo Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
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
System.Object
Oracle.DataAccess.Client.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();
glob.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or laterMicrosoft .NET Framework Version:
2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Members
■ OracleGlobalization Static Methods
■ OracleGlobalization Properties
■ OracleGlobalization Public Methods
■ Oracle Database SQL Reference
■ Oracle Database Globalization Support Guide
OracleGlobalization Members
OracleGlobalization Properties
The OracleGlobalization properties are listed in Table 10–2.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
Example
// C#
using System;
using Oracle.DataAccess.Client;
class GetClientInfoSample
{
static void Main()
{
// Get client's globalization info
OracleGlobalization glob = OracleGlobalization.GetClientInfo();
glob.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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();
glob.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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;
class GetThreadInfoSample
{
static void Main()
{
// Get thread's globalization info
OracleGlobalization glob = OracleGlobalization.GetThreadInfo();
glob.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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
glob.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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();
glob1.Dispose();
glob2.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
OracleGlobalization Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
Calendar
This property specifies the calendar system.
Declaration
// C#
public string Calendar {get; set;}
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 or not the OracleGlobalization object represents the
settings of the client, thread, or session.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
Remarks
The default value is the NLS_COMP setting of the local computer.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
■ Oracle Database SQL Reference for further information on the L
number format element
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-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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-3
■ OracleGlobalization Class
■ OracleGlobalization Members
■ Oracle Database SQL Reference for further information on the U
number format element
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
■ Oracle Database SQL Reference for further information on the C
number format element
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.
Language is used for messages, day and month names, and sorting algorithms. It also
determines NLS_DATE_LANGUAGE and NLS_SORT parameter values.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
LengthSemantics
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
NCharConversionException
This property determines whether or not 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-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
■ Oracle Database Globalization Support Guide.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
TimeStampTZFormat
This property specifies the string format for TimeStampTZ types.
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
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.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleGlobalization Class
■ OracleGlobalization Members
OracleFailoverEventArgs Class
Class Inheritance
System.Object
System.EventArgs
Oracle.DataAccess.Client.OracleFailoverEventArgs
Declaration
// C#
public sealed class OracleFailoverEventArgs
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
// C#
using System;
using System.Threading;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
class FailoverSample
{
static void Main(string[] args)
{
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
OracleConnection con = new OracleConnection(constr);
con.Open();
con.Close();
con.Dispose();
}
{
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");
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
Comment: Not supported in a .NET stored procedure
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleFailoverEventArgs Members
■ OracleFailoverEventArgs Static Methods
■ OracleFailoverEventArgs Properties
■ OracleFailoverEventArgs Public Methods
■ "OracleConnection Class" on page 5-64
■ Oracle Net Services Administrator's Guide
OracleFailoverEventArgs Members
OracleFailoverEventArgs Properties
The OracleFailoverEventArgs properties are listed in Table 11–2.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleFailoverEventArgs Class
■ "FailoverType Enumeration" on page 11-12
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleFailoverEventArgs Class
■ OracleFailoverEventArgs Members
OracleFailoverEventArgs Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleFailoverEventArgs Class
■ OracleFailoverEventArgs Members
FailoverType
This property indicates the state of the failover.
Declaration
// C#
public FailoverType FailoverType {get;}
Property Value
A FailoverType enumeration value.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleFailoverEventArgs Class
■ OracleFailoverEventArgs Members
■ "FailoverType Enumeration" on page 11-12
FailoverEvent
This property indicates the state of the failover.
Declaration
// C#
public FailoverEvent FailoverEvent {get;}
Property Value
A FailoverEvent enumerated value.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleFailoverEventArgs Class
■ OracleFailoverEventArgs Members
■ "FailoverEvent Enumeration" on page 11-10
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleFailoverEventArgs Class
■ OracleFailoverEventArgs Members
OracleFailoverEventHandler Delegate
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);
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
Comment: Not supported in a .NET stored procedure
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleFailoverEventArgs Class
■ OracleFailoverEventArgs Members
■ "Failover" on page 5-110
FailoverEvent Enumeration
FailoverEvent enumerated values are used to specify the state of the failover.
Table 11–7 lists all the FailoverEvent enumeration values with a description of each
enumerated value.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ FailoverEvent Enumeration on page 11-10
■ "OracleFailoverEventArgs Class" on page 11-2
■ "FailoverEvent" on page 11-7
■ Oracle Database Oracle Clusterware and Oracle Real Application
Clusters Administration and Deployment Guide
■ Oracle Net Services Reference Guide
FailoverReturnCode Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ FailoverEvent Enumeration on page 11-10
■ "OracleFailoverEventArgs Class" on page 11-2
■ "FailoverEvent" on page 11-7
■ Oracle Database Oracle Clusterware and Oracle Real Application
Clusters Administration and Deployment Guide
■ Oracle Net Services Reference Guide
FailoverType Enumeration
FailoverType enumerated values are used to indicate the type of failover event that
was raised.
Table 11–9 lists all the FailoverType enumeration values with a description of each
enumerated value.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ FailoverEvent Enumeration on page 11-10
■ "OracleFailoverEventArgs Class" on page 11-2
■ "FailoverType" on page 11-7
■ Oracle Database Oracle Clusterware and Oracle Real Application
Clusters Administration and Deployment Guide
■ Oracle Net Services Reference Guide
This chapter describes the following Oracle Data Provider for .NET classes:
■ OracleAQAgent Class
■ OracleAQDequeueOptions Class
■ OracleAQEnqueueOptions Class
■ OracleAQMessage Class
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventHandler Delegate
■ OracleAQQueue Class
■ OracleAQDequeueMode Enumeration
■ OracleAQMessageDeliveryMode Enumeration
■ OracleAQMessageState Enumeration
■ OracleAQMessageType Enumeration
■ OracleAQNavigationMode Enumeration
■ OracleAQNotificationGroupingType Enumeration
■ OracleAQNotificationType Enumeration
■ OracleAQVisibilityMode Enumeration
OracleAQAgent Class
Class Inheritance
System.Object
OracleAQAgent
Declaration
// C#
public sealed class OracleAQAgent
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
An agent may be a consumer, another queue, or a consumer of another queue. The
queue may be either local or remote. A remote queue is specified through a database
link.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQAgent Members
■ OracleAQAgent Constructors
■ OracleAQAgent Properties
OracleAQAgent Members
OracleAQAgent Constructors
OracleAQAgent constructors are listed in Table 12–1.
OracleAQAgent Properties
OracleAQAgent properties are listed in Table 12–2.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQAgent Class
OracleAQAgent Constructors
Overload List:
■ OracleAQAgent (string)
This constructor instantiates the OracleAQAgent class using the specified name.
■ OracleAQAgent (string, string)
This constructor instantiates the OracleAQAgent class using the specified name
and address.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQAgent Class
■ OracleAQAgent Members
OracleAQAgent (string)
This constructor instantiates the OracleAQAgent class using the specified name.
Declaration
// C#
public OracleAQAgent(string name);
Parameters
■ name
The name of the agent.
Exceptions
ArgumentNullException - The name parameter is null.
ArgumentException - The name parameter is empty.
Remarks
The agent name signifies the name of a producer or consumer of a message. In the
context of functionality exposed by Listen, an agent name corresponds to the name
of a consumer for which a message is expected on a multiconsumer queue. It may also
be set on a message to signify sender identification or intended recipients of the
message.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQAgent Class
■ OracleAQAgent Members
Declaration
// C#
public OracleAQAgent(string name, string address);
Parameters
■ name
The name of the agent.
■ address
The address is of the form [schema.]queue[@dblink].
Exceptions
ArgumentNullException - The address parameter is null.
ArgumentException - The address parameter is empty.
Remarks
The agent name signifies the name of a producer or consumer of a message. In the
context of functionality exposed by Listen, an agent name corresponds to the name
of a consumer for which a message is expected on a multiconsumer queue.
The name parameter can be specified as null in this constructor. In such a scenario,
the agent only has an address.
The address parameter signifies the name of the queue against which this agent
listens for new messages. The address represents a queue at a local or remote
database.The validity of the address is not checked implicitly. The exceptions due to
wrong address are thrown only during database operations such as Listen.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQAgent Class
■ OracleAQAgent Members
OracleAQAgent Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQAgent Class
■ OracleAQAgent Members
Address
This instance property specifies the address of the agent.
Declaration
// C#
public string Address {get; }
Property Value
A string that specifies the agent address.
Remarks
The address represents a queue at a local or remote database. The default value is
null. The address of the agent is of the form [schema.]queue[@dblink]. The string
length can be up to 128 characters.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQAgent Class
■ OracleAQAgent Members
Name
This instance property specifies the name of the agent.
Declaration
// C#
public string Name {get; }
Property Value
A string.
Remarks
The default is null. The string length can be up to 30 characters. A non-null value
implies that this agent name either corresponds to a consumer name in a
multiconsumer queue, or a recipient as specified in message properties.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQAgent Class
■ OracleAQAgent Members
OracleAQDequeueOptions Class
Class Inheritance
System.Object
OracleAQDequeueOptions
Declaration
// C#
public sealed class OracleAQDequeueOptions : ICloneable
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Members
■ OracleAQDequeueOptions Constructor
■ OracleAQDequeueOptions Properties
■ OracleAQDequeueOptions Public Methods
OracleAQDequeueOptions Members
OracleAQDequeueOptions Constructor
The OracleAQDequeueOptions constructor is listed in Table 12–4.
OracleAQDequeueOptions Properties
OracleAQDequeueOptions properties are listed in Table 12–5.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
OracleAQDequeueOptions Constructor
Declaration
// C#
public OracleAQDequeueOptions();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
OracleAQDequeueOptions Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
ConsumerName
This instance property specifies the consumer name for which to dequeue the
message.
Declaration
// C#
public string ConsumerName {get;set;}
Property Value
A string.
Remarks
The ConsumerName property only accesses those messages that match the consumer
name. If a queue is not set up for multiple consumers, then this field should be set to
null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
Correlation
This instance property specifies the correlation identifier of the message to be
dequeued.
Declaration
// C#
public string Correlation {get;set;}
Property Value
A string.
Remarks
This property specifies the identification of the message to be dequeued. Special
pattern matching characters, such as the percent sign (%) and the underscore (_) can be
used. If more than one message satisfies the pattern, then the order of dequeuing is
undetermined.
The maximum length of Correlation is 128.
MessageId and Correlation are two independent identifiers. While MessageId is
unique for a message, a group of messages can be assigned the same Correlation.
Also, pattern matching is possible only with Correlation.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
DeliveryMode
This instance property specifies the expected delivery mode of the message being
dequeued.
Declaration
// C#
public OracleAQMessageDeliveryMode DeliveryMode {get;set;}
Property Value
An OracleAQMessageDeliveryMode enumerated value.
Remarks
This property specifies the type of messages to be dequeued. It can be set to dequeue
either persistent or buffered messages, or both from a queue. The following values are
valid:
■ OracleAQMessageDeliveryMode.Persistent
■ OracleAQMessageDeliveryMode.Buffered
■ OracleAQMessageDeliveryMode.PersistentOrBuffered
The default value is OracleAQMessageDeliveryMode.Persistent.
Buffered messaging is supported in all queue tables created with a database
compatibility level of 8.1 or higher.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
DequeueMode
This instance property specifies the locking behavior associated with the dequeue
operation.
Declaration
// C#
public OracleAQDequeueMode DequeueMode {get;set;}
Property Value
An OracleAQDequeueMode enumerated value.
Exceptions
ArgumentOutOfRangeException - The specified DequeueMode value is invalid.
Remarks
The default value is OracleAQDequeueMode.Remove.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
MessageId
This instance property specifies the message identifier of the message to be dequeued.
Declaration
// C#
public byte[] MessageId {get;set;}
Property Value
A byte[ ].
Remarks
The dequeue operation succeeds only if the message ID of the message being
dequeued matches with the message ID specified.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
NavigationMode
This instance property specifies the position of the message that will be retrieved.
Declaration
// C#
public OracleAQNavigationMode NavigationMode {get;set;}
Property Value
An OracleAQNavigationMode enumerated value.
Exceptions
ArgumentOutOfRangeException - The specified NavigationMode value is
invalid.
Remarks
The default value is OracleAQNavigationMode.NextMessage.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
ProviderSpecificType
This property specifies whether the payload of a dequeued message is provided as an
ODP.NET specific type or a .NET type.
Declaration
// C#
public bool ProviderSpecificType {get;set;}
Property Value
A bool.
Remarks
The default value of this property is false. For a discussion of how this property
affects payload type, refer to "MessageType" under the OracleAQQueue class.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
■ "MessageType" on page 12-60
Visibility
This instance property specifies whether or not the new message is dequeued as part
of the current transaction.
Declaration
// C#
public OracleAQVisibilityMode Visibility {get;set;}
Property Value
An OracleAQVisibilityMode enumerated value.
Exceptions
ArgumentOutOfRangeException - The Visibility value specified is invalid.
Remarks
The default value is OracleAQVisibilityMode.OnCommit. It is strongly
recommended to use transactions when using the default value for this property. This
ensures that applications do not loose messages and the messages are appropriately
removed from the queue after the dequeue operation is successful. If transactions are
not used when using the default visibility mode of
OracleAQVisibilityMode.OnCommit, then messages are not removed from the
queue.
Using the alternative visibility mode value,
OracleAQVisibilityMode.Immediate can eliminate the need to create, commit,
and rollback a transaction. However, if an error occurs during the dequeue operation,
then the message may be lost.
The visibility parameter is ignored when DequeueMode is set to
OracleAQDequeueMode.Browse.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
Wait
This instance property specifies the wait time, in seconds, for a message that matches
the search criteria.
Declaration
// C#
public int Wait {get;set;}
Property Value
Any positive integer value or 0 or -1.
Exceptions
ArgumentOutOfRangeException - The specified Wait value is invalid.
Remarks
The default value is -1, which implies an infinite wait. The following values are valid:
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
Clone
This method creates a copy of an OracleAQDequeueOptions object.
Declaration
// C#
public object Clone();
Return Value
An OracleAQDequeueOptions object.
Implements
ICloneable.
Remarks
The cloned object has the same property values as the object being cloned.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQDequeueOptions Class
■ OracleAQDequeueOptions Members
OracleAQEnqueueOptions Class
Class Inheritance
System.Object
OracleAQEnqueueOptions
Declaration
// C#
public sealed class OracleAQEnqueueOptions : ICloneable
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQEnqueueOptions Members
■ OracleAQEnqueueOptions Constructor
■ OracleAQEnqueueOptions Properties
■ OracleAQEnqueueOptions Public Methods
OracleAQEnqueueOptions Members
OracleAQEnqueueOptions Constructor
OracleAQEnqueueOptions constructor is listed in Table 12–9.
OracleAQEnqueueOptions Properties
OracleAQEnqueueOptions properties are listed in Table 12–10.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQEnqueueOptions Class
OracleAQEnqueueOptions Constructor
Declaration
// C#
public OracleAQEnqueueOptions();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQEnqueueOptions Class
■ OracleAQEnqueueOptions Members
OracleAQEnqueueOptions Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQEnqueueOptions Class
■ OracleAQEnqueueOptions Members
DeliveryMode
This instance property specifies the delivery mode of the message being enqueued.
Declaration
// C#
public OracleAQMessageDeliveryMode DeliveryMode {get;set;}
Exceptions
ArgumentOutOfRangeException - The specified Visibility value is invalid.
Remarks
The valid values can be any of the following enumerated values:
■ OracleAQMessageDeliveryMode.Persistent
■ OracleAQMessageDeliveryMode.Buffered
The default is OracleAQMessageDeliveryMode.Persistent.
OracleAQMessageDeliveryMode.PersistentOrBuffered cannot be set on this
property.
OracleAQMessageDeliveryMode.Buffered can be specified only with Oracle
Database 10g release 2 (10.2) or higher. Buffered messaging is supported in all queue
tables created with a database compatibility level of 8.1 or higher.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQEnqueueOptions Class
■ OracleAQEnqueueOptions Members
Visibility
This instance property specifies whether or not the new message is enqueued as part
of the current transaction.
Declaration
// C#
public OracleAQVisibilityMode Visibility {get;set;}
Property Value
An OracleAQVisibilityMode enumerated value.
Exceptions
ArgumentOutOfRangeException - The specified Visibility value is invalid.
Remarks
The default value is OracleAQVisibilityMode.OnCommit. Use transactions when
using the default value in order to commit or rollback the enqueue. If transactions are
not used when using the default visibility mode of
OracleAQVisibilityMode.OnCommit, then messages are not enqueued to the
queue.
Using the alternative visibility mode value,
OracleAQVisibilityMode.Immediate eliminates the need to use a transaction.
The queue is not affected in case the enqueue operation fails. The message does not get
enqueued to the queue for such cases.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQEnqueueOptions Class
■ OracleAQEnqueueOptions Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQEnqueueOptions Class
■ OracleAQEnqueueOptions Members
Clone
This method creates a copy of an OracleAQEnqueueOptions object.
Declaration
// C#
public object Clone();
Return Value
An OracleAQEnqueueOptions object.
Implements
ICloneable.
Remarks
The cloned object has the same property values as that of the object being cloned.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQEnqueueOptions Class
■ OracleAQEnqueueOptions Members
OracleAQMessage Class
Class Inheritance
System.Object
OracleAQMessage
Declaration
// C#
public sealed class OracleAQMessage
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
An OracleAQMessage object consists of control information (metadata) and Payload
(data). The control information is exposed by various properties on the
OracleAQMessage object and is used by Oracle Streams Advanced Queuing to
manage messages. The payload is the information stored in the queue.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Members
■ OracleAQMessage Constructors
■ OracleAQMessage Properties
OracleAQMessage Members
OracleAQMessage Constructor
OracleAQMessage constructors are listed in Table 12–14.
OracleAQMessage Properties
OracleAQMessage properties are listed in Table 12–15.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
OracleAQMessage Constructors
Overload List:
■ OracleAQMessage()
This constructor instantiates the OracleAQMessage class.
■ OracleAQMessage(Object)
This constructor instantiates the OracleAQMessage class using the object
provided as the payload.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
OracleAQMessage()
This constructor instantiates the OracleAQMessage class.
Declaration
// C#
public OracleAQMessage();
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
OracleAQMessage(Object)
This constructor instantiates the OracleAQMessage class using the Object provided
as the payload.
Declaration
// C#
public OracleAQMessage(Object payload);
Parameters
■ payload
An Object specifying payload. It can be one of the following types:
– byte[]
– IOracleCustomType
– OracleBinary
– OracleXmlType
– String
– XmlReader
Exceptions
ArgumentException - The specified payload value is of invalid type.
Remarks
The ODP.NET AQ implementation currently does not support user defined types with
LOB attributes. It also does not support other variants of user defined types such as
VARRAY and nested tables, as Oracle Streams AQ does not support them inherently.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
OracleAQMessage Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
Correlation
This instance property specifies an identification for the message.
Declaration
// C#
public string Correlation {get;set;}
Property Value
A string that specifies the identification for the message.
Remarks
The producer of a message can set this property at the time of enqueuing. The
consumer can then use this identification to dequeue specific messages by setting the
Correlation property of an OracleAQDequeueOptions object. For more
information regarding dequeuing messages based on Correlation, refer to
"Correlation" under the OracleAQDequeueOptions class.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
■ "Correlation" on page 12-13
Delay
This instance property specifies the duration, in seconds, after which an enqueued
message is available for dequeuing.
Declaration
// C#
public int Delay {get;set;}
Property Value
An integer that indicates the number of seconds after which an enqueued message
is available for dequeuing.
Exceptions
ArgumentException - The value specified is less than 0.
Remarks
This property delays the immediate consumption of an enqueued message. The
following are valid values for this property:
■ Positive integer - Indicates the delay in seconds.
■ 0 - indicates that the message is immediately available for dequeuing.
The default value is 0. The Delay property is not supported with buffered messaging.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
DeliveryMode
This instance property specifies the delivery mode of the dequeued message.
Declaration
// C#
public OracleAQMessageDeliveryMode DeliveryMode {get;}
Property Value
An OracleAQMessageDeliveryMode enumerated value
(OracleAQMessageDeliveryMode.Persistent or
OracleAQMessageDeliveryMode.Buffered).
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
DequeueAttempts
This instance property returns the number of attempts that have been made to
dequeue the message.
Declaration
// C#
public int DequeueAttempts {get;}
Property Value
An integer that indicates the number of dequeue attempts.
Remarks
This property is available in an OracleAQMessage after the message has been
dequeued from a queue.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
EnqueueTime
This instance property specifies the time when the message was enqueued.
Declaration
// C#
public DateTime EnqueueTime {get;}
Property Value
A DateTime object.
Remarks
This property is available after the message is dequeued. It provides the enqueue time
of a dequeued message.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
ExceptionQueue
This instance property specifies the name of the queue that the message should be
moved to if it cannot be processed successfully.
Declaration
// C#
public string ExceptionQueue {get;set;}
Property Value
The name of the queue that a message should be moved to if it cannot be processed
successfully. The default value is null.
Remarks
This property specifies the queue that a message should be moved to if the message
has expired or if the number of unsuccessful dequeue attempts have exceeded the
max_retries value for the queue.
If this property is not set or the specified exception queue name does not exist, then
the default exception queue associated with the queue table is used.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
Expiration
This instance property specifies the duration, in seconds, for which an enqueued
message is available for dequeuing.
Declaration
// C#
public int Expiration {get;set;}
Property Value
An integer that specifies the number of seconds an enqueued message is available
for dequeuing.
Exceptions
ArgumentException - The value specified is less than -1.
Remarks
The value specified is an offset from the value specified in the Delay property.
The following are valid values for the property:
■ Positive integer - Indicates the expiration in seconds.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
MessageId
This instance property returns the message identifier.
Declaration
// C#
public byte[] MessageId {get;}
Property Value
A byte[] that specifies the message identifier.
Remarks
This property is available after an enqueue or dequeue operation. Dequeued buffered
messages have a null value for MessageId.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
OriginalMessageId
This instance property specifies the identifier of the message in the last queue that
generated this message.
Declaration
// C#
public byte[] OriginalMessageId {get;}
Property Value
A byte[] that specifies the original message identifier.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
Payload
This instance property specifies the payload of the message.
Declaration
// C#
public Object Payload {get;set;}
Property Value
An Object that specifies the payload of the message.
Exceptions
ArgumentException - The specified object is not one of the allowed types.
Remarks
For a complete discussion of various payload types, refer to "MessageType" under the
OracleAQQueue class.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
■ "MessageType" on page 12-60
Priority
This instance property specifies the priority of the message.
Declaration
// C#
public int Priority {get;set;}
Property Value
An integer that specifies the priority of the message.
Remarks
The default value is 0. In order to take effect, this property must be set prior to
enqueuing the message.
Smaller values indicate higher priority for the message. Negative values may also be
used.
The priority of an enqueued message is useful for priority-based dequeuing.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
Recipients
This instance property specifies the list of recipients that overrides the default queue
subscribers.
Declaration
// C#
Property Value
An OracleAQAgent[].
Remarks
This recipient list is valid only for messages being enqueued to multiconsumer queues.
The list of recipients is not returned with the message at the time of dequeuing.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
SenderId
This instance property identifies the original sender of the message.
Declaration
// C#
public OracleAQAgent SenderId {get; set}
Property Value
An OracleAQAgent object.
Remarks
Sender identification is supported in all queue tables created with a database
compatibility level of 8.1 or higher.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
State
This instance property specifies the state of the message at the time of dequeue.
Declaration
// C#
public OracleAQMessageState State {get;}
Property Value
An OracleAQMessageState enumerated value.
Remarks
This property is available after the message is dequeued.
The state of buffered messages dequeued by specifying Correlation under dequeue
options is always OracleAQMessageState.Ready.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
TransactionGroup
This instance property specifies the transaction group for the dequeued message.
Declaration
// C#
public string TransactionGroup {get;}
Property Value
A string that specifies the transaction group.
Remarks
This property is set only after the call to DequeueArray. This property is supported
only when using Oracle Database 10g database or higher.
Messages belonging to one queue can be grouped to form a set that can only be
consumed by one user at a time. This requires that the queue be created in a queue
table that is enabled for message grouping. All messages belonging to a group must be
created in the same transaction. Also, all messages created in one transaction belong to
the same group.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessage Class
■ OracleAQMessage Members
OracleAQMessageAvailableEventArgs Class
Class Inheritance
System.Object
System.EventArgs
Oracle.DataAccess.Client.OracleAQMessageAvailableEventArgs
Declaration
// C#
public sealed class OracleAQMessageAvailableEventArgs
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
This class cannot be inherited.
For detailed information on all the inherited properties and methods, please read the
documentation provided by Microsoft's .NET Documentation.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Members
■ OracleAQMessageAvailableEventArgs Properties
OracleAQMessageAvailableEventArgs Members
OracleAQMessageAvailableEventArgs Properties
OracleAQMessageAvailableEventArgs properties are listed in Table 12–17.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
OracleAQMessageAvailableEventArgs Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
AvailableMessages
This instance property specifies the number of messages that raised this notification.
Declaration
// C#
public int AvailableMessages{get;}
Property Value
An integer indicating the number of messages that raised this notification.
Remarks
The property value is 1 for a regular notification type. The notification type can be
specified using the OracleAQQueue.Notification property.
This property is not relevant if the NotificationType is
OracleAQNotificationType.Timeout.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
ConsumerName
This property provides the name of the consumer for which the message is available
for dequeuing.
Declaration
// C#
public string ConsumerName {get;}
Property Value
A string that identifies the name of the consumer.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
Correlation
This instance property specifies the identification for the message.
Declaration
// C#
public string Correlation {get;}
Property Value
A string that specifies the identification for the message.
Remarks
This property specifies the correlation of the message for which the notification is
raised. The consumer can then use this identification to dequeue specific messages by
setting the "Correlation" property of the OracleAQDequeueOptions object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
■ "Correlation" on page 13
Delay
This instance property specifies the duration, in seconds, after which an enqueued
message is available for dequeuing.
Declaration
// C#
public int Delay {get;}
Property Value
An integer that indicates the duration, in seconds, after which an enqueued message
is available for dequeuing.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
DeliveryMode
This instance property specifies the delivery mode of the message.
Declaration
// C#
public OracleAQMessageDeliveryMode DeliveryMode {get;}
Property Value
An OracleAQMessageDeliveryMode enumerated value.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
EnqueueTime
This instance property specifies the time when the message was enqueued.
Declaration
// C#
public DateTime EnqueueTime {get;}
Property Value
A DateTime object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
ExceptionQueue
This instance property specifies the name of the queue that the message is moved to if
it cannot be processed successfully.
Declaration
// C#
public string ExceptionQueue {get;}
Property Value
The name of the queue that a message to is moved if it cannot be processed
successfully.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
Expiration
This instance property specifies the duration, in seconds, for which an enqueued
message is available for dequeuing before expiring.
Declaration
// C#
public int Expiration {get;}
Property Value
An integer that specifies the duration, in seconds, for which an enqueued message is
available for dequeuing.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
MessageId
This instance property returns an array of message identifiers.
Declaration
// ADO.NET 2.0: C#
public byte[ ][ ] MessageId{get;}
Property Value
A byte[ ][ ] that specifies the message identifiers received as part of the
notification.
Remarks
This property specifies the message identifiers of the messages that raise the
notification.
The size of the MessageId array is 1 for regular notifications. The size of the
MessageId array is 1 for grouping notifications if the notification grouping type is
OracleAQNotificationGroupingType.Last.
This property is not relevant if the NotificationType is
OracleAQNotificationType.Timeout.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
NotificationType
This property indicates the type of notification such as regular, grouping, or timeout.
Declaration
// C#
public OracleAQNotificationType NotificationType {get;}
Property Value
An OracleAQNotificationType enum value.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
OriginalMessageId
This property specifies the ID of the message, in the last queue, that generated this
message.
Declaration
// C#
public byte[] OriginalMessageId {get;}
Property Value
A byte[] that specifies the original message ID.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
Priority
This instance property specifies the priority of the message.
Declaration
// C#
public int Priority {get;}
Property Value
An integer that specifies the priority of the message.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
QueueName
This property indicates the name of the queue that contains the message to be
dequeued.
Declaration
// C#
public string QueueName {get;}
Property Value
A string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
SenderId
This property identifies the original sender of the message.
Declaration
// C#
public OracleAQAgent SenderId {get;}
Property Value
An OracleAQAgent object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
State
This instance property specifies the state of the message.
Declaration
// C#
public OracleAQMessageState State {get;}
Property Value
An OracleAQMessageState enumerated value.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQMessageAvailableEventArgs Class
■ OracleAQMessageAvailableEventArgs Members
OracleAQMessageAvailableEventHandler Delegate
Declaration
// C#
public delegate void OracleAQMessageAvailableEventHandler (object
sender,OracleAQMessageAvailableEventArg eventArgs);
Parameters
■ sender
The source of the event.
■ eventArgs
The OracleAQMessageAvailableEventArgs object that contains the event
data.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "MessageAvailable Event" on page 12-78
OracleAQQueue Class
Class Inheritance
System.Object
OracleAQQueue
Declaration
// C#
public class OracleAQQueue : IDisposable
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
A queue is a repository of messages and may either be a user queue, or an exception
queue. A user queue is for normal message processing. A message is moved from a
user queue to an exception queue if it cannot be retrieved and processed for some
reason.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Members
■ OracleAQQueue Constructors
■ OracleAQQueue Static Methods
■ OracleAQQueue Properties
■ OracleAQQueue Public Methods
■ OracleAQQueue Events
OracleAQQueue Members
OracleAQQueue Constructors
OracleAQQueue constructors are listed in Table 12–19.
OracleAQQueue Properties
OracleAQQueue properties are listed in Table 12–21.
OracleAQQueue Events
The OracleAQQueue event is listed in Table 12–23.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
OracleAQQueue Constructors
Overload List:
■ OracleAQQueue(string)
This constructor takes a queue name to initialize a queue object.
■ OracleAQQueue(string, OracleConnection)
This constructor takes a queue name and connection to initialize a queue object.
The connection does not need be open during the queue object construction.
■ OracleAQQueue(string, OracleConnection, OracleAQMessageType)
This constructor takes a queue name, connection, and message type enumeration
to initialize a queue object.
■ OracleAQQueue(string, OracleConnection, OracleAQMessageType, string)
This constructor takes a queue name, connection, message type enumeration, and
UDT type name to initialize a queue object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
OracleAQQueue(string)
This constructor takes a queue name to initialize a queue object.
Declaration
// C#
public OracleAQQueue(string name);
Parameters
■ name
The name of the queue as specified in the database.
Exceptions
ArgumentNullException - The queue name is null.
ArgumentException - The queue name is empty.
Remarks
The operation of creating an OracleAQQueue object does not involve checking for the
existence of the queue in the database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
OracleAQQueue(string, OracleConnection)
This constructor takes a queue name and connection to initialize a queue object. The
connection does not need to be open during the queue object construction.
Declaration
// C#
public OracleAQQueue(string name, OracleConnection con);
Parameters
■ name
Name of the queue as specified in the database.
■ con
An OracleConnection object that connects to the queue.
Exceptions
ArgumentNullException - Either the connection is null or queue name is null.
ArgumentException - Queue name is empty.
Remarks
The connection can be accessed using the Connection property, and it must be
opened before calling any operational APIs such as Enqueue and Dequeue.
Creating an OracleAQQueue object does not check for the existence of the queue in
the database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Declaration
// C#
public OracleAQQueue(string name, OracleConnection con, OracleAQMessageType
messageType);
Parameters
■ name
The name of the queue as specified in the database.
■ con
An OracleConnection object that is used to connect to the queue.
■ messageType
Exceptions
ArgumentNullException - Either the connection is null or queue name is null.
ArgumentException - Queue name is empty or the specified message type is not
valid.
Remarks
Creating an OracleAQQueue object does not check for the existence of the queue in
the database.
You need to set the UdtTypeName property before using the queue object if the
messageType is a UDT. Another approach is to create a queue using the other
constructor overload by supplying the udtTypeName.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Declaration
// C#
public OracleAQQueue(string name, OracleConnection con, OracleAQMessageType
messageType, string udtTypeName);
Parameters
■ name
The name of the queue as specified in the database.
■ con
An OracleConnection object that is used to connect to the queue.
■ messageType
An OracleAQMessageType enumeration specifying the type of the message that
is enqueued or dequeued from this queue.
■ udtTypeName
The name of the database object type used if the messageType is UDT. The
udtTypeName parameter represents the type on which the queue is based.
Exceptions
ArgumentNullException - The connection is null or the queue name is null.
ArgumentException - The queue name is empty or the specified messageType is
not valid.
Remarks
Creating an OracleAQQueue object does not check for the existence of the queue in
the database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Listen
Listen methods listen for messages on one or more queues for one or more
consumers as specified in the array of OracleAQAgent objects.
Overload list
■ Listen(OracleConnection, OracleAQAgent[ ])
This static method listens for messages on one or more queues for one or more
consumers as specified in the array of OracleAQAgent objects.
■ Listen(OracleConnection, OracleAQAgent[ ], int)
This static method listens for messages on one or more queues for one or more
consumers as specified in the array of OracleAQAgent objects. It also specifies a
wait time.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Listen(OracleConnection, OracleAQAgent[ ])
This static method listens for messages on one or more queues for one or more
consumers as specified in the array of OracleAQAgent objects.
Declaration
// C#
public static OracleAQAgent Listen(OracleConnection con, OracleAQAgent[]
listenConsumers);
Parameters
■ con
An OracleConnection instance.
■ listenConsumers
The array of consumers being listened for. The name of the OracleAQAgent
object must be null or empty for single consumer queues.
Return Value
An OracleAQAgent object.
Exceptions
ArgumentNullException - The con or listenConsumers parameter is null.
InvalidOperationException - The connection is not open.
Remarks
Listen is useful in situations where one needs to monitor multiple queues until a
message is available for a consumer in one of the queues. The Name property of the
OracleAQAgent object represents the name of the consumer and the Address
property represents the name of the queue.
This call blocks the calling thread until there is a message ready for consumption for a
consumer in the list. It returns an OracleAQAgent object which specifies the
consumer and queue for which a message is ready to be dequeued.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Declaration
// C#
public static OracleAQAgent Listen(OracleConnection con, OracleAQAgent[]
listenConsumers, int waitTime);
Parameters
■ con
An OracleConnection instance.
■ listenConsumers
The array of consumers being listened for. The name of the OracleAQAgent
object must be null or empty for single consumer queues.
■ waitTime
Wait time in seconds.
Return Value
An OracleAQAgent object.
Exceptions
ArgumentNullException - The con or listenConsumers parameter is null.
InvalidOperationException - The connection is not open.
ArgumentException - waitTime is less than -1.
Remarks
Listen is useful in situations where one needs to monitor multiple queues until a
message is available for a consumer in one of the queues. The Name property of the
OracleAQAgent object represents the name of the consumer and the Address
property of the OracleAQAgent object represents the name of the queue.
A waitTime of -1 implies an infinite wait time.
This call blocks the calling thread until there is a message ready for consumption for a
consumer in the list. It returns an OracleAQAgent object which specifies the
consumer and queue for which a message is ready to be dequeued.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
OracleAQQueue Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Connection
This property specifies the OracleConnection object associated with the queue.
Declaration
// C#
public OracleConnection Connection {get; set;}
Property Value
An OracleConnection object that indicates the connection associated with the
queue.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
This connection must be opened before calling methods like Enqueue and Dequeue.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
DequeueOptions
This instance property specifies the dequeueing options to use when dequeuing a
message from a queue.
Declaration
// C#
public OracleAQDequeueOptions DequeueOptions {get; set}
Property Value
An OracleAQDequeueOptions object.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
The default value is an OracleAQDequeueOptions object with default property
values. Setting this property to null resets all dequeue options to their default values.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
EnqueueOptions
This instance property specifies the enqueueing options used to enqueue a message to
a queue.
Declaration
// C#
public OracleAQEnqueueOptions EnqueueOptions {get; set}
Property Value
An OracleAQEnqueueOptions object.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
The default value is an OracleAQEnqueueOptions object with default property
values. Setting this property to null resets all enqueue options to their default values.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
MessageType
This instance property specifies the type of queue table associated with this queue.
Declaration
// C#
public OracleAQMessageType MessageType {get; set;}
Property Value
An OracleAQMessageType enumerated value.
Exceptions
ArgumentOutOfRangeException - The type value specified is invalid.
ObjectDisposedException - The object is already disposed.
Remarks
The MessageType property also dictates the type of message payloads that are
enqueued or dequeued from the queue. It is possible to enqueue a variety of payloads
depending on the MessageType.
Table 12–26 lists the allowed payload types for various message types.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Name
This instance property returns the name of the queue.
Declaration
// C#
public string Name {get;}
Property Value
A string that indicates the name of the queue.
Exceptions
ObjectDisposedException - The object is already disposed.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Notification
This instance property specifies the various notification options for notifications that
are registered using the MessageAvailable event.
Declaration
// C#
public OracleNotificationRequest Notification {get;}
Property Value
Specifies an OracleNotificationRequest object whose properties can be changed
to alter the notification behavior.
Remarks
This property can be used to change various notification options. The notification
options must be changed before registering with the MessageAvailable event. This
property can be modified again only after unregistering from the
MessageAvailable event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
NotificationConsumers
This instance property specifies the array of consumers, for a multiconsumer queue,
that are to be notified asynchronously for any incoming messages on the queue.
Declaration
// C#
public string[] NotificationConsumers {get; set;}
Property Value
Specifies an array of consumer name strings for which the notifications are delivered.
Exceptions
ObjectDisposedException - The object is already disposed.
InvalidOperationException - MessageAvailable registration is active.
Remarks
The consumer names must be in uppercase. This functionality only supports queues
with uppercase names.
The list of consumers is used in the MessageAvailable event. The list must be set
before registering for the event. This property cannot be modified after registering for
the MessageAvailable event. This property can be modified again only after
unregistering from MessageAvailable event.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
UdtTypeName
This instance property specifies the type name on which the queue and the
corresponding queue table is based if the MessageType is
OracleAQMessageType.UDT.
Declaration
// C#
public string UdtTypeName {get; set;}
Property Value
Specifies the Oracle user-defined type name if the MessageType is
OracleAQMessageType.UDT.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
The UdtTypeName property corresponds to the user-defined type name of the
payload. This property must always be specified if the payload is a user-defined type.
This property need not be set for other payload types.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Dequeue
Dequeue methods dequeue messages from queues.
Overload List
■ Dequeue()
This instance method dequeues messages from a queue using the
DequeueOptions for the instance.
■ Dequeue(OracleAQDequeueOptions)
This instance method dequeues messages from a queue using the supplied
dequeue options.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Dequeue()
This instance method is used to dequeue a message from a queue using the
DequeueOptions for the instance.
Declaration
// C#
Return Value
An OracleAQMessage instance representing the dequeued message.
Exceptions
InvalidOperationException - The connection is not open.
ObjectDisposedException - The object is already disposed.
OracleException - In case of timeout, an exception is thrown with the message,
ORA-25228: timeout or end-of-fetch during message dequeue from
queue_name.Timeout may happen if DequeueOptions.Wait is set to a value other
than -1.
Remarks
The MessageType property must be set appropriately before calling this function. If
the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property
must also be set.
Dequeued buffered messages always have null MessageId values.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Dequeue(OracleAQDequeueOptions)
This instance method dequeues messages from a queue using the supplied dequeue
options.
Declaration
// C#
public OracleAQMessage Dequeue(OracleAQDequeueOptions dequeueOptions);
Parameters
■ dequeueOptions
An OracleAQDequeueOptions object.
Return Value
An OracleAQMessage instance representing the dequeued message.
Exceptions
InvalidOperationException - The connection is not open.
ObjectDisposedException - The object is already disposed.
OracleException - In case of timeout, an exception is thrown with the message,
ORA-25228: timeout or end-of-fetch during message dequeue from
queue_name. Timeout may happen if DequeueOptions.Wait is set to a value
other than -1.
Remarks
If the supplied dequeueOptions object is null, then the dequeue options default
values are used. The queue object's DequeueOptions property is ignored for this
operation.
Calling this method does not change the DequeueOptions property of the queue.
The MessageType property must be set appropriately before calling this function. If
the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property
must also be set.
Dequeued buffered messages always have null MessageId values.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
DequeueArray
DequeueArray methods dequeue multiple messages from queues.
Overload List
■ DequeueArray(int)
This instance method dequeues multiple messages from a queue using the
DequeueOptions of the instance.
■ DequeueArray(int, OracleAQDequeueOptions)
This instance method dequeues multiple messages from a queue using the
supplied dequeue options.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
DequeueArray(int)
This instance method dequeues multiple messages from a queue using the
DequeueOptions of the instance.
Declaration
// C#
public OracleAQMessage[] DequeueArray(int dequeueCount);
Parameters
■ dequeueCount
An integer specifying the numbers of messages to dequeue.
Return Value
An array of OracleAQMessage instances representing the dequeued messages.
Exceptions
ArgumentOutOfRangeException - dequeueCount is less than or equal to 0.
InvalidOperationException - The connection is not open.
ObjectDisposedException - The object is already disposed.
OracleException - In case of timeout, an exception is thrown with the message,
ORA-25228: timeout or end-of-fetch during message dequeue from
queue_name. Timeout may happen if DequeueOptions.Wait is set to a value
other than -1.
Remarks
This method is supported for Oracle Database 10g and higher releases.
The MessageType property must be set appropriately before calling this function. If
the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property
must be set as well.
The size of the returned array may be less than the dequeueCount. It depends on the
actual number of messages present in the queue.
The MessageId property of OracleAQMessage objects retrieved using
DequeueArray is always null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
DequeueArray(int, OracleAQDequeueOptions)
This instance method dequeues multiple messages from a queue using the supplied
dequeue options.
Declaration
// C#
public OracleAQMessage[] DequeueArray(int dequeueCount, OracleAQDequeueOptions
dequeueOptions);
Parameters
■ dequeueCount
An integer specifying the numbers of messages to dequeue.
■ dequeueOptions
An OracleAQDequeueOptions object.
Return Value
An array of OracleAQMessage instances representing the dequeued messages.
Exceptions
ArgumentOutOfRangeException - dequeueCount is less than or equal to 0.
InvalidOperationException - The connection is not open.
ObjectDisposedException - The object is already disposed.
Remarks
This method is supported for Oracle Database 10g Release 1 (10.1) and higher releases.
Calling this method does not change the DequeueOptions property of the queue.
If the supplied dequeueOptions object is null, then the dequeue options default
values are used. The DequeueOptions property of the queue object is ignored in this
operation.
The MessageType property must be set appropriately before calling this function. If
the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property
must be set as well.
The size of the returned array may be less than the dequeueCount. It dependes on
the actual number of messages present in the queue.
The MessageId property of OracleAQMessage objects retrieved using
DequeueArray is always null.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Dispose
This method releases any resources or memory allocated by the object.
Declaration
// C#
public void Dispose();
Implements
IDisposable.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Enqueue
Enqueue instance methods enqueue messages to queues.
Overload List
■ Enqueue(OracleAQMessage)
This instance method enqueues messages to a queue using the EnqueueOptions
of the instance.
■ Enqueue(OracleAQMessage, OracleAQEnqueueOptions)
This instance method enqueues messages to a queue using the supplied enqueue
options.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Enqueue(OracleAQMessage)
This instance method enqueues messages to a queue using the EnqueueOptions of
the instance.
Declaration
// C#
public void Enqueue(OracleAQMessage message);
Parameters
■ message
An OracleAQMessage object.
Exceptions
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The connection is not open.
ArgumentNullException - The message parameter is null.
ArgumentException - The message payload is OracleXmlType and the connection
used to create OracleXmlType is different from the queue's connection.
Remarks
MessageId of the enqueued message is populated after the call to Enqueue
completes. Enqueued buffered messages always have null MessageId values.
The MessageType property needs to be set appropriately before calling this function.
If the MessageType is OracleAQMessageType.UDT, then the UdtTypeName
property must be set as well.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Enqueue(OracleAQMessage, OracleAQEnqueueOptions)
This instance method enqueues messages to a queue using the supplied enqueue
options.
Declaration
// C#
public void Enqueue(OracleAQMessage message, OracleAQEnqueueOptions
enqueueOptions);
Parameters
■ message
An OracleAQMessage object.
■ enqueueOptions
An OracleAQEnqueueOptions object.
Exceptions
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The connection is not open.
ArgumentNullException - The message parameter is null.
ArgumentException - The message payload is OracleXmlType and the connection
used to create OracleXmlType is different from the queue's connection.
Remarks
If the supplied enqueueOptions object is null, then the enqueue options default
values are used. The EnqueueOptions property of the queue object is ignored in this
operation.
The MessageId of the enqueued message is populated after the call to Enqueue
completes. Enqueued buffered messages always have null MessageId values.
Calling this method does not change the EnqueueOptions property of the queue.
The MessageType property must be set appropriately before calling this function. If
the MessageType is OracleAQMessageType.UDT, then the UdtTypeName
property must also be set.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
EnqueueArray
EnqueueArray instance methods enqueue multiple messages to a queue.
Overload List
■ EnqueueArray(OracleAQMessage[ ])
This instance method enqueues multiple messages to a queue using the
EnqueueOptions of the instance.
■ EnqueueArray(OracleAQMessage[ ], OracleAQEnqueueOptions)
This instance method enqueues multiple messages to a queue using the supplied
enqueue options.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
EnqueueArray(OracleAQMessage[ ])
This instance method enqueues multiple messages to a queue using the
EnqueueOptions of the instance.
Declaration
// C#
public int EnqueueArray(OracleAQMessage[] messages);
Parameters
■ messages
An array of OracleAQMessage objects.
Return Value
An integer representing the number of messages actually enqueued.
Exceptions
ArgumentNullException - The message parameter is null.
ArgumentException - At least one of the OracleAQMessage[] elements is null,
or at least one of the OracleAQMessage[] elements has a payload of
OracleXmlType, which is created using a connection that is different from the
queue's connection.
InvalidOperationException - The OracleAQMessage array is empty or the
connection is not open.
ObjectDisposedException - The object is already disposed.
Remarks
This method is supported by Oracle Database 10g and higher releases. The
MessageId properties of the enqueued messages are populated after the call to
Enqueue completes. Enqueued buffered messages always have null MessageId
values.
The MessageType property must be set appropriately before calling this function. If
the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property
must also be set.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
EnqueueArray(OracleAQMessage[ ], OracleAQEnqueueOptions)
This instance method enqueues multiple messages to a queue using the supplied
enqueue options.
Declaration
// C#
public int EnqueueArray(OracleAQMessage[] messages, OracleAQEnqueueOptions
enqueueOptions);
Parameters
■ messages
An array of OracleAQMessage objects.
■ enqueueOptions
An OracleAQEnqueueOptions object.
Return Value
An integer representing the number of messages actually enqueued.
Exceptions
ArgumentNullException - The message parameter is null.
ArgumentException - At least one of the OracleAQMessage[] elements is null,
or at least one of the OracleAQMessage[] elements has a payload of
OracleXmlType, which is created using a connection that is different from the
queue's connection.
InvalidOperationException - The OracleAQMessage array is empty or the
connection is not open.
ObjectDisposedException - The object is already disposed.
Remarks
This method is supported by Oracle Database 10g and higher releases. MessageId
properties of the enqueued messages are populated after the call to Enqueue
completes. Enqueued buffered messages always have null MessageId values.
Calling this method does not change the EnqueueOptions property of the queue.
If the supplied enqueueOptions object is null, then the enqueue options default
values are used. The EnqueueOptions property of the queue object is ignored in this
operation.
The MessageType property must be set appropriately before calling this function. If
the MessageType is OracleAQMessageType.UDT, then the UdtTypeName property
must also be set.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Listen
Listen methods listen for messages on the queue on behalf of listenConsumers.
Overload List
■ Listen(string[])
This method listens for messages on the queue on behalf of listenConsumers.
■ string Listen (string[], int)
This method listens for messages on behalf of listenConsumers for a specified
time.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Listen(string[])
This method listens for messages on the queue on behalf of listenConsumers.
Declaration
// C#
public string Listen(string[] listenConsumers);
Parameters
■ listenConsumers
An array of consumers to listen for on this queue. This parameter should be null
in case of single consumer queues.
Return Value
A string.
Exceptions
InvalidOperationException - The connection is not open.
ObjectDisposedException - The object is already disposed.
Remarks
This call blocks the calling thread until there is a message ready for consumption for a
consumer in the listenConsumers array. It returns a string representing the
consumer name for which the message is ready.
Listen is useful in situations that require waiting until a message is available in the
queue for consumers whose names are specified in listenConsumers.
Example
The following example demonstrates using the Listen method. The first part of the
example performs the requisite database setup for the database user, SCOTT. The
second part of the example demonstrates how a thread can listen and wait until a
message is enqueued.
-- Part I: Database setup required for this demo
------------------------------------------------------------------
-- SQL to grant appropriate privilege to database user, SCOTT
------------------------------------------------------------------
SQL> ALTER USER SCOTT ACCOUNT UNLOCK IDENTIFIED BY Pwd4Sct;
User altered.
GRANT ALL ON DBMS_AQADM TO scott;
------------------------------------------------------------------
-- PLSQL to create queue-table and queue and start queue for SCOTT
------------------------------------------------------------------
BEGIN
DBMS_AQADM.CREATE_QUEUE_TABLE(
queue_table=>'scott.test_q_tab',
queue_payload_type=>'RAW',
multiple_consumers=>FALSE);
DBMS_AQADM.CREATE_QUEUE(
queue_name=>'scott.test_q',
queue_table=>'scott.test_q_tab');
DBMS_AQADM.START_QUEUE(queue_name=>'scott.test_q');
END;
/
------------------------------------------------------------------
-- PLSQL to stop queue and drop queue & queue-table from SCOTT
------------------------------------------------------------------
BEGIN
DBMS_AQADM.STOP_QUEUE('scott.test_q');
DBMS_AQADM.DROP_QUEUE(
queue_name => 'scott.test_q',
auto_commit => TRUE);
DBMS_AQADM.DROP_QUEUE_TABLE(
queue_table => 'scott.test_q_tab',
force => FALSE,
auto_commit => TRUE);
END;
/
-- End of Part I, database setup.
namespace ODPSample
{
/// <summary>
/// Demonstrates how a thread can listen and wait until a message is enqueued.
/// Once a message is enqueued, the listening thread returns from the
/// blocked Listen() method invocation and dequeues the message.
/// </summary>
class EnqueueDequeue
{
static bool s_bListenReturned = false;
// Create queue
OracleAQQueue queue = new OracleAQQueue("scott.test_q", con);
try
{
// Open connection
con.Open();
System.Threading.Thread.Sleep(2000);
// Prepare to Enqueue
queue.EnqueueOptions.Visibility = OracleAQVisibilityMode.OnCommit;
// Enqueue message
queue.Enqueue(enqMsg);
// Create queue
OracleAQQueue queueListen = new OracleAQQueue("scott.test_q", conListen);
try
{
// Open the connection for Listen thread.
// Connection blocked on Listen thread can not be used for other DB
// operations
conListen.Open();
// Listen
queueListen.Listen(null);
// Prepare to Dequeue
queueListen.DequeueOptions.Visibility = OracleAQVisibilityMode.OnCommit;
queueListen.DequeueOptions.Wait = 10;
// Dequeue message
OracleAQMessage deqMsg = queueListen.Dequeue();
Console.WriteLine("[Listen Thread] Dequeued Message Payload : "
+ ByteArrayToString(deqMsg.Payload as byte[]));
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
Declaration
// C#
public string Listen(string[] listenConsumers, int waitTime);
Parameters
■ listenConsumers
Array of consumers for which to listen on this queue.
■ waitTime
Wait time in seconds.
Return Value
A string
Exceptions
InvalidOperationException - The connection is not open.
ArgumentException - waitTime is less than -1.
ObjectDisposedException - The object is already disposed.
Remarks
Listen is useful in situations that require waiting until a message is available in the
queue for consumers whose names are specified in listenConsumers.
This call blocks the calling thread until there is a message ready for consumption for a
consumer in the listenConsumers array. It returns a string representing the
consumer name for which the message is ready.The method returns null if a timeout
occurs.
The listenConsumers parameter should be null for single consumer queues. An
empty string is returned in such cases.
A waitTime of -1 implies infinite wait time.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
OracleAQQueue Events
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
MessageAvailable Event
This event is notified when a message is available in the queue for
NotificationConsumers.
Declaration
// C#
public event OracleAQMessageAvailableEventHandler MessageAvailable;
Event Data
The event handler receives an OracleAQMessageAvailableEventArgs object.
Exceptions
InvalidOperationException - The connection is not open.
Remarks
Asynchronous notification is supported in all queue tables created with a database
compatibility level of 8.1 or higher.
In order to receive the notification about message availability, the client must create an
OracleAQMessageAvailableEventHandler delegate to listen to this event. The
delegate should be added to this event only after setting the NotificationConsumers
and Notification properties.
The notification registration takes place after the first delegate is added to the event.
The notification is unregistered when the last delegate is removed from the event.
Notifications set on an OracleAQQueue object get cancelled automatically when the
object gets disposed.
Oracle Data Provider for .NET opens a port to listen for notifications. HA events, load
balancing, and database change notification features also share the same port. This
port can be configured centrally by setting the database notification port in an
application or Web configuration file. The following example code specifies a port
number of 1200:
<configuration>
<oracle.dataaccess.client>
<settings>
If the configuration file does not exist or the db notification port is not specified, then
ODP.NET uses a valid and random port number. The configuration file may also
request for a random port number by specifying a db notification port value of -1.
The notification listener, which runs in the same application domain as ODP.NET, uses
the specified port number to listen to notifications from the database. A notification
listener gets created when the application registers with
OracleAQQueue.MessageAvailable event. One notification listener can listen to
all notification types. Only one notification listener is created for each application
domain.
Example
The following example demonstrates application notification. The first part of the
example performs the requisite database setup for the database user, SCOTT. The
second part of the example demonstrates how an application is notified when a
message is available in the queue.
-- Part I: Database setup required for this demo
------------------------------------------------------------------
-- SQL to grant appropriate privilege to database user, SCOTT
------------------------------------------------------------------
SQL> ALTER USER SCOTT ACCOUNT UNLOCK IDENTIFIED BY Pwd4Sct;
User altered.
SQL> GRANT ALL ON DBMS_AQADM TO scott;
------------------------------------------------------------------
-- PLSQL to create queue-table and queue and start queue for SCOTT
------------------------------------------------------------------
BEGIN
DBMS_AQADM.CREATE_QUEUE_TABLE(
queue_table=>'scott.test_q_tab',
queue_payload_type=>'RAW',
multiple_consumers=>FALSE);
DBMS_AQADM.CREATE_QUEUE(
queue_name=>'scott.test_q',
queue_table=>'scott.test_q_tab');
DBMS_AQADM.START_QUEUE(queue_name=>'scott.test_q');
END;
/
------------------------------------------------------------------
-- PLSQL to stop queue and drop queue & queue-table from SCOTT
------------------------------------------------------------------
BEGIN
DBMS_AQADM.STOP_QUEUE('scott.test_q');
DBMS_AQADM.DROP_QUEUE(
queue_name => 'scott.test_q',
auto_commit => TRUE);
DBMS_AQADM.DROP_QUEUE_TABLE(
namespace ODPSample
{
/// <summary>
/// Demonstrates how the application can be notified when a message is
/// available in a queue.
/// </summary>
class Notification
{
static bool isNotified = false;
// Create queue
OracleAQQueue queue = new OracleAQQueue("scott.test_q", con);
try
{
// Open connection
con.Open();
Console.WriteLine("Notification registered...");
// Prepare to Enqueue
queue.EnqueueOptions.Visibility = OracleAQVisibilityMode.OnCommit;
// Enqueue message
queue.Enqueue(enqMsg);
return sb.ToString();
}
}
}
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleAQQueue Class
■ OracleAQQueue Members
OracleAQDequeueMode Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleAQDequeueOptions Class" on page 12-8
■ "DequeueMode" on page 12-14
OracleAQMessageDeliveryMode Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleAQDequeueOptions Class" on page 12-8
■ "DeliveryMode" on page 12-13
OracleAQMessageState Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleAQMessage Class" on page 12-25
■ "State" on page 12-36
OracleAQMessageType Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleAQQueue Class" on page 12-48
■ "OracleAQQueue Constructors" on page 12-51
■ "MessageType" on page 12-60
OracleAQNavigationMode Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleAQDequeueOptions Class" on page 12-8
■ "NavigationMode" on page 12-15
OracleAQNotificationGroupingType Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleNotificationRequest Class" on page 9-22
OracleAQNotificationType Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
OracleAQVisibilityMode Enumeration
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
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
Class Inheritance
System.Object
System.MarshalByRefObject
System.IO.Stream
Oracle.DataAccess.Types.OracleBFile
Declaration
// C#
public sealed class OracleBFile : Stream, ICloneable, INullable
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 later.
Example
// Database Setup, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
*/
// C#
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
class OracleBFileSample
{
static void Main()
{
// Create MYDIR directory object as indicated previously and create a file
// MyFile.txt with the text ABCDABC under C:\TEMP directory.
// Note that the byte representation of the ABCDABC is 65666768656667
bFile.Close();
bFile.Dispose();
con.Close();
con.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Members
■ OracleBFile Constructors
■ OracleBFile Static Fields
■ OracleBFile Static Methods
■ OracleBFile Instance Properties
■ OracleBFile Instance Methods
OracleBFile Members
OracleBFile Constructors
OracleBFile constructors are listed in Table 13–1.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Members
OracleBFile Constructors
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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-9
■ OracleBFile Class
■ OracleBFile Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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 or not the operation exceeds the
maximum length allowed.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
Null
This static field represents a null value that can be assigned to the value of an
OracleBFile instance.
Declaration
// C#
public static readonly OracleBFile Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
CanRead
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
CanSeek
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
CanWrite
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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-9
■ OracleBFile Class
■ OracleBFile Members
IsNull
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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-9
■ OracleBFile Class
■ OracleBFile Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
*/
// C#
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
class CloneSample
{
static void Main()
{
// Create MYDIR directory object as indicated previously and create a file
// MyFile.txt with the text ABCDABC under C:\TEMP directory.
// Note that the byte representation of the ABCDABC is 65666768656667
bFile1.Close();
bFile1.Dispose();
bFile2.Close();
bFile2.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
CloseFile
This instance method closes the BFILE referenced by the current BFILE instance.
Declaration
// C#
public void CloseFile();
Remarks
No error is returned if the BFILE exists, but is not opened.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
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, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
*/
// C#
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
class CompareSample
{
static void Main()
{
// Create MYDIR directory object as indicated previously and create a file
// MyFile.txt with the text ABCDABC under C:\TEMP directory.
// Note that the byte representation of the ABCDABC is 65666768656667
bFile1.Close();
bFile1.Dispose();
bFile2.Close();
bFile2.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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-9
■ OracleBFile Class
■ OracleBFile Members
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.
■ 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-9
■ OracleBFile Class
■ OracleBFile Members
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.
■ 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-9
■ OracleBFile Class
■ OracleBFile Members
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-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
Dispose
This instance method releases resources allocated by this object.
Declaration
// C#
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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-9
■ OracleBFile Class
■ OracleBFile Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
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, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
*/
// C#
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
class ReadSample
{
static void Main()
{
// Create MYDIR directory object as indicated previously and create a file
// MyFile.txt with the text ABCDABC under C:\TEMP directory.
// Note that the byte representation of the ABCDABC is 65666768656667
{
Console.Write(readBuffer[index]);
}
Console.WriteLine();
bFile.Close();
bFile.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
*/
// C#
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
class SearchSample
{
static void Main()
{
// Create MYDIR directory object as indicated previously and create a file
// MyFile.txt with the text ABCDABC under C:\TEMP directory.
// Note that the byte representation of the ABCDABC is 65666768656667
bFile.Close();
bFile.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
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.
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, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
*/
// 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 previously and create a file
// MyFile.txt with the text ABCDABC under C:\TEMP directory.
// Note that the byte representation of the ABCDABC is 65666768656667
bFile.Close();
bFile.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBFile Class
■ OracleBFile Members
OracleBlob Class
Class Inheritance
System.Object
System.MarshalByRefObject
System.IO.Stream
Oracle.DataAccess.Types.OracleBlob
Declaration
// C#
public sealed class OracleBlob : Stream, ICloneable, INullable
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();
blob.Close();
blob.Dispose();
con.Close();
con.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Members
■ OracleBlob Constructors
■ OracleBlob Static Fields
■ OracleBlob Static Methods
■ OracleBlob Instance Properties
■ OracleBlob Instance Methods
OracleBlob Members
OracleBlob Constructors
OracleBlob constructors are listed in Table 13–10.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Members
OracleBlob Constructors
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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 or not the operation exceeds the
maximum length allowed.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
Null
This static field represents a null value that can be assigned to the value of an
OracleBlob instance.
Declaration
// C#
public static readonly OracleBlob Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
CanRead
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
CanSeek
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
CanWrite
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
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 or not the BLOB is empty.
Exceptions
ObjectDisposedException - The object is already disposed.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
IsInChunkWriteMode
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
IsNull
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
IsTemporary
This instance property indicates whether or not the current instance is bound to a
temporary BLOB.
Declaration
// C#
public bool IsTemporary {get;}
Property Value
bool
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
OptimumChunkSize
This instance property indicates the optimal data buffer length (or multiples thereof)
that read and write operations should use to improve performance.
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-9
■ OracleBlob Class
■ OracleBlob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
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 AppendSample
{
static void Main()
{
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
OracleConnection con = new OracleConnection(constr);
con.Open();
blob.Close();
blob.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
BeginChunkWrite
This instance method opens the BLOB.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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
{
static void Main()
{
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
OracleConnection con = new OracleConnection(constr);
con.Open();
blob1.Close();
blob1.Dispose();
blob2.Close();
blob2.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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
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-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
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()
{
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
OracleConnection con = new OracleConnection(constr);
con.Open();
blob1.Close();
blob1.Dispose();
blob2.Close();
blob2.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
Erase()
This instance method erases all data.
Declaration
// C#
public Int64 Erase();
Return Value
The number of bytes erased.
Remarks
Erase() replaces all data with zero-byte fillers.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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-9
■ OracleBlob Class
■ OracleBlob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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
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();
blob.Close();
blob.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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.
■ 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();
blob.Close();
blob.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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.
InvalidOperationException - The OracleConnection is not open or has been
closed during the lifetime of the object.
ArgumentOutOfRangeException - The newlen parameter is less than 0.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
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
{
static void Main()
{
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
OracleConnection con = new OracleConnection(constr);
con.Open();
blob.Close();
blob.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBlob Class
■ OracleBlob Members
OracleClob Class
An OracleClob is an object that has a reference to CLOB data. It provides methods for
performing operations on CLOBs.
Note: The OracleClob object uses the client side character set
when retrieving or writing CLOB data using a .NET Framework
byte array.
Class Inheritance
System.Object
System.MarshalByRefObject
System.IO.Stream
Oracle.DataAccess.Types.OracleClob
Declaration
// C#
public sealed class OracleClob : Stream, ICloneable, INullable
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();
clob.Close();
clob.Dispose();
con.Close();
con.Dispose();
}
}
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Members
■ OracleClob Constructors
■ OracleClob Static Fields
■ OracleClob Static Methods
■ OracleClob Instance Properties
■ OracleClob Instance Methods
OracleClob Members
OracleClob Constructors
OracleClob constructors are listed in Table 13–19.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
OracleClob Constructors
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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 or not your operation exceeds the
maximum length (in bytes) allowed.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
Null
This static field represents a null value that can be assigned to the value of an
OracleClob instance.
Declaration
// C#
public static readonly OracleClob Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
CanRead
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
CanSeek
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
CanWrite
Overrides Stream
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
IsInChunkWriteMode
This instance property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
IsNCLOB
This instance property indicates whether or not the OracleClob object represents an
NCLOB.
Declaration
// C#
public bool IsNCLOB {get;}
Property Value
A bool.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
IsNull
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
OptimumChunkSize
This instance property indicates the minimum number of bytes to retrieve or send
from the database 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-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
Value
This instance property returns the data, starting from the first character in the CLOB or
NCLOB, as a string.
Declaration
// C#
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-9
■ OracleClob Class
■ OracleClob Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
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-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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();
clob.Close();
clob.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
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();
clob1.Close();
clob1.Dispose();
clob2.Close();
clob2.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
Close
Overrides Stream
This instance method closes the current stream and releases resources associated with
it.
Declaration
// C#
public override void Close();
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
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-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
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.
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();
clob1.Close();
clob1.Dispose();
clob2.Close();
clob2.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
Dispose
This instance method releases resources allocated by this object.
Declaration
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-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
Erase()
This instance method erases all data.
Declaration
// C#
public Int64 Erase();
Return Value
The number of characters erased.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
GetHashCode
Overrides Object
Declaration
// C#
public override int GetHashCode();
Return Value
An int representing a hash code.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
Read
Read reads a specified amount from the current instance and populates the array
buffer.
Overload List:
■ Read(byte [ ], int, int)
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
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
{
static void Main()
{
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
OracleConnection con = new OracleConnection(constr);
con.Open();
clob.Close();
clob.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
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.
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();
clob.Close();
clob.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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-9
■ OracleClob Class
■ OracleClob Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
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.
■ 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();
clob.Close();
clob.Dispose();
con.Close();
con.Dispose();
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleClob Class
■ OracleClob Members
OracleRefCursor Class
Class Inheritance
System.Object
System.MarshalRefByObject
Oracle.DataAccess.Types.OracleRefCursor
Declaration
// C#
public sealed class OracleRefCursor : MarshalByRefObject, IDisposable, INullable
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
To minimize the number of open server cursors, OracleRefReader objects should be
explicitly disposed.
Example
// Database Setup
/*
connect scott/tiger@oracle
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 previously
// Create an OracleCommand
OracleCommand cmd = new OracleCommand("MyFunc", con);
cmd.CommandType = CommandType.StoredProcedure;
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Members
■ OracleRefCursor Static Methods
■ OracleRefCursor Properties
■ OracleRefCursor Instance Methods
OracleRefCursor Members
OracleRefCursor Properties
OracleRefCursor properties are listed in Table 13–29.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
■ OracleRefCursor Members
OracleRefCursor Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
■ OracleRefCursor Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
■ OracleRefCursor Members
FetchSize
This property specifies the size that the OracleDataReader internal cache needs to
store result set data.
Declaration
// C#
public long FetchSize {get; set;}
Property Value
A long that specifies the size (in bytes) of the OracleRefCursor internal cache.
Exceptions
ArgumentException - The FetchSize value specified is invalid.
Remarks
Default = 131072.
The FetchSize property value is inherited by the OracleCommand that created the
OracleRefCursor object. The FetchSize property on the OracleDataReader
object determines the amount of data the OracleRefCursor fetches into its internal
cache for each database round-trip.
This property is useful if the OracleRefCursor is explicitly used to fill the DataSet
or DataTable through the OracleDataAdapter, because it can provide control on
how the data of the REF CURSOR is fetched.
If an OracleDataReader object is created from the OracleRefCursor, the
resulting OracleDataReader object inherits the FetchSize value of the
OracleDataReader object. However, the inherited value can be overridden, if it is
set before the first invocation of the OracleDataReader Read method for the given
result set, by setting the OracleDataReader FetchSize property.
The RowSize and FetchSize properties handle UDT and XMLType data differently
than other scalar data types. Because only a reference to the UDT and XMLType data is
stored in the ODP.NET's internal cache, the RowSize property accounts for only the
memory needed for the reference (which is very small) and not the actual size of the
UDT and XMLType data. Thus, applications can inadvertently fetch a large number of
UDT or XMLType instances from the database in a single database round-trip. This is
because the actual size of UDT and XMLType data does not count against the
FetchSize, and it would require numerous UDT and XMLType references to fill up
the default cache size of 131072 bytes. Therefore, when fetching UDT or XMLType
data, the FetchSize property must be appropriately configured to control the
number of UDT and XMLType instances that are to be fetched, rather than the amount
of the actual UDT and XMLType data to be fetched.
NOTE: For LOB and LONG data types, only the sizes specified in the
InitialLOBFetchSize and InitialLONGFetchSize properties are accounted for
by the RowSize property in addition to the metadata and reference information that is
maintained by the cache for each LOB in the select list.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
■ OracleRefCursor Members
RowSize
This property specifies the amount of memory the OracleRefcursor internal cache
needs to store one row of data.
Declaration
// C#
public long RowSize {get;}
Property Value
A long that indicates the amount of memory (in bytes) that an OracleRefcursor
needs to store one row of data for the executed query.
Remarks
The RowSize property is set to a nonzero value when the OracleRefcursor object
is created. 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
OracleRefcursor to fetch N rows for each database round-trip, the
OracleRefcursor FetchSize property can be set dynamically to RowSize * N.
Note that for the FetchSize to take effect appropriately, it must be set before the it is
used to fill the DataSet/DataTable using OracleDataAdapter.
If an OracleDataReader is obtained from the OracleRefCursor through the
GetDataReader method, the resulting OracleDataReader will have its
FetchSize property set to the FetchSize value of the OracleRefCursor.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
■ OracleRefCursor Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
■ OracleRefCursor Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
■ OracleRefCursor Members
GetDataReader
This instance method returns an OracleDataReader object for the REF CURSOR.
Declaration
// C#
Return Value
OracleDataReader
Remarks
Using the OracleDataReader, rows can be fetched from the REF CURSOR.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRefCursor Class
■ OracleRefCursor Members
Types Structures
OracleBinary Structure
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleBinary
Declaration
// ADO.NET 2.0: C#
public struct OracleBinary : IComparable, INullable, IXmlSerializable
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;
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ 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
OracleBinary Constructors
OracleBinary constructors are listed in Table 14–1
OracleBinary Properties
The OracleBinary properties are listed in Table 14–6.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
OracleBinary Constructor
Declaration
// C#
public OracleBinary(byte[ ] bytes);
Parameters
■ bytes
A byte array.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
Concat
This method returns the concatenation of two OracleBinary structures.
Declaration
// C#
public static OracleBinary Concat(OracleBinary value1, OracleBinary value2);
Parameters
■ value1
The first OracleBinary.
■ value2
The second OracleBinary.
Return Value
An OracleBinary.
Remarks
If either argument has a null value, the returned OracleBinary structure has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
Equals
This method determines if two OracleBinary values are equal.
Declaration
// C#
public static bool Equals(OracleBinary value1, OracleBinary value2);
Parameters
■ value1
The first OracleBinary.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
GreaterThan
This method determines whether or not the first of two OracleBinary values is
greater than the second.
Declaration
// C#
public static bool GreaterThan(OracleBinary value1, OracleBinary value2);
Parameters
■ value1
The first OracleBinary.
■ value2
The second OracleBinary.
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});
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
GreaterThanOrEqual
This method determines whether or not 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
The first OracleBinary.
■ value2
The second OracleBinary.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
LessThan
This method determines whether or not the first of two OracleBinary values is less
than the second.
Declaration
// C#
public static bool LessThan(OracleBinary value1, OracleBinary value2);
Parameters
■ value1
The first OracleBinary.
■ value2
The 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-9
■ OracleBinary Structure
■ OracleBinary Members
LessThanOrEqual
This method determines whether or not 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
The first OracleBinary.
■ value2
The 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-9
■ OracleBinary Structure
■ OracleBinary Members
NotEquals
This method determines whether or not two OracleBinary values are not equal.
Declaration
// C#
public static bool NotEquals(OracleBinary value1, OracleBinary value2);
Parameters
■ value1
The first OracleBinary.
■ value2
The 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.
■ 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-9
■ OracleBinary Structure
■ OracleBinary Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
operator +
This method concatenates two OracleBinary values.
Declaration
// C#
public static OracleBinary operator + (OracleBinary value1, OracleBinary value2);
Parameters
■ value1
The first OracleBinary.
■ value2
The second OracleBinary.
Return Value
OracleBinary
Remarks
If either argument has a null value, the returned OacleBinary structure has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
operator ==
This method determines if two OracleBinary values are equal.
Declaration
// C#
public static bool operator == (OracleBinary value1, OracleBinary value2);
Parameters
■ value1
The first OracleBinary.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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
The first OracleBinary.
■ value2
The second OracleBinary.
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});
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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
The first OracleBinary.
■ value2
The second OracleBinary.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
operator !=
This method determines if two OracleBinary values are not equal.
Declaration
// C#
public static bool operator != (OracleBinary value1, OracleBinary value2);
Parameters
■ value1
The first OracleBinary.
■ value2
The second OracleBinary.
Return Value
Returns true if the two OracleBinary values are not equal; otherwise, returns
false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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
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-9
■ OracleBinary Structure
■ OracleBinary Members
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
The first OracleBinary.
■ value2
The 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-9
■ OracleBinary Structure
■ OracleBinary Members
The OracleBinary static type conversion operators are listed in Table 14–11.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
Declaration
// C#
public static implicit operator OracleBinary(byte[ ] bytes);
Parameters
■ bytes
A byte array.
Return Value
OracleBinary
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
OracleBinary Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
IsNull
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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.
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});
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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});
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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-9
■ OracleBinary Structure
■ OracleBinary Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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.
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");
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
Equals
This method determines whether or not 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.
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-9
■ OracleBinary Structure
■ OracleBinary Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleBinary Structure
■ OracleBinary Members
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-9
■ OracleBinary Structure
■ OracleBinary Members
OracleDate Structure
The OracleDate structure represents the Oracle DATE data type to be stored in or
retrieved from a database. Each OracleDate stores the following information: year,
month, day, hour, minute, and second.
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleDate
Declaration
// ADO.NET 2.0: C#
public struct OracleDate : IComparable, INullable, IXmlSerializable
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);
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Members
■ OracleDate Constructors
■ OracleDate Static Fields
■ OracleDate Static Methods
■ OracleDate Static Operators
■ OracleDate Static Type Conversions
■ OracleDate Properties
■ OracleDate Methods
OracleDate Members
OracleDate Constructors
OracleDate constructors are listed in Table 14–14
OracleDate Properties
The OracleDate properties are listed in Table 14–19.
OracleDate Methods
The OracleDate methods are listed in Table 14–20.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
OracleDate Constructors
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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-9
■ OracleDate Structure
■ OracleDate Members
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 the Oracle 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);
// Print "12/01/1999"
Console.WriteLine(date.ToString());
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
■ "OracleGlobalization Class" on page 10-2
■ Oracle Database SQL Reference for further information on date
format elements
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).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
Declaration
// C#
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).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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-9
■ OracleDate Structure
■ OracleDate Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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-9
■ OracleDate Structure
■ OracleDate Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
Equals
Overloads Object
This method determines if two OracleDate values are equal.
Declaration
// C#
public static bool Equals(OracleDate value1, OracleDate value2);
Parameters
■ value1
The first OracleDate.
■ value2
The 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.
■ 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-9
■ OracleDate Structure
■ OracleDate Members
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
The first OracleDate.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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);
Parameters
■ value1
The first OracleDate.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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
The first OracleDate.
■ value2
The 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-9
■ OracleDate Structure
■ OracleDate Members
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
The first OracleDate.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
NotEquals
This method determines if two OracleDate values are not equal.
Declaration
// C#
public static bool NotEquals(OracleDate value1, OracleDate value2);
Parameters
■ value1
The first OracleDate.
■ value2
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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.
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 the Oracle 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);
// Print "12-01-1999"
Console.WriteLine(date.ToString());
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
■ Oracle Database SQL Reference for further information on
datetime format elements
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
operator ==
This method determines if two OracleDate values are the same.
Declaration
// C#
public static bool operator == (OracleDate value1, OracleDate value2);
Parameters
■ value1
The first OracleDate.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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
The first OracleDate.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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
The first OracleDate.
■ value2
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
operator !=
This method determines if the two OracleDate values are not equal.
Declaration
// C#
public static bool operator != (OracleDate value1, OracleDate value2);
Parameters
■ value1
The first OracleDate.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
operator <
This method determines if the first of two OracleDate values is less than the second.
Declaration
// C#
public static bool operator < (OracleDate value1, OracleDate value2);
Parameters
■ value1
The first OracleDate.
■ value2
The 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-9
■ OracleDate Structure
■ OracleDate Members
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
The first OracleDate.
■ value2
The 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-9
■ OracleDate Structure
■ OracleDate Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
Declaration
// C#
public static explicit operator DateTime(OracleDate val);
Parameters
■ val
An OracleDate structure.
Return Value
A DateTime structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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)
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
Declaration
// C#
public static explicit operator OracleDate(DateTime dt);
Parameters
■ dt
A DateTime structure.
Return Value
An OracleDate structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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-9
■ OracleDate Structure
■ OracleDate Members
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 the Oracle
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-9
■ OracleDate Structure
■ OracleDate Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
OracleDate Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
Day
This property gets the day component of an OracleDate.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
IsNull
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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-9
■ OracleDate Structure
■ OracleDate Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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-9
■ OracleDate Structure
■ OracleDate Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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-9
■ OracleDate Structure
■ OracleDate Members
OracleDate Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
Equals
This method determines whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
GetHashCode
Overrides Object
This method returns a hash code for the OracleDate instance.
Declaration
// C#
public override int GetHashCode();
Return Value
A number that represents the hash code.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
ToOracleTimeStamp
This method converts the current OracleDate structure to an OracleTimeStamp
structure.
Declaration
// C#
public OracleTimeStamp ToOracleTimeStamp();
Return Value
An OracleTimeStamp structure.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
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);
// Prints "1999/12/01"
Console.WriteLine(date.ToString());
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDate Structure
■ OracleDate Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
OracleDecimal Structure
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleDecimal
Declaration
// ADO.NET 2.0: C#
public struct OracleDecimal : IComparable, INullable, IXmlSerializable
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 data type can
only hold up to 28 precision. When accessing the OracleDecimal.Value property
from an OracleDecimal that has a value greater than 28 precision, an exception is
thrown. 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);
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ 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 Members
OracleDecimal Constructors
OracleDecimal constructors are listed in Table 14–27
OracleDecimal Properties
The OracleDecimal properties are listed in Table 14–36.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Structure
OracleDecimal Constructors
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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);
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
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)
{
// Print "$2,222.22"
Console.WriteLine(dec.ToString());
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
MaxPrecision
This static field represents the maximum precision, which is 38.
Declaration
// C#
public static readonly byte MaxPrecision;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
MaxScale
This static field a constant representing the maximum scale, which is 127.
Declaration
// C#
public static readonly byte MaxScale;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
MinScale
This static field indicates a constant representing the maximum scale, which is -84.
Declaration
// C#
public static readonly int MinScale;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
NegativeOne
This static field indicates a constant representing the negative one value.
Declaration
// C#
public static readonly OracleDecimal NegativeOne;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Null
This static field represents a null value that can be assigned to an OracleDecimal
instance.
Declaration
// C#
public static readonly OracleDecimal Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
One
This static field indicates a constant representing the positive one value.
Declaration
// C#
public static readonly OracleDecimal One;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Equals
This method determines if two OracleDecimal values are equal.
Declaration
// C#
public static bool Equals(OracleDecimal value1, OracleDecimal value2);
Parameters
■ value1
The first OracleDecimal.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
The first OracleDecimal.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
The first OracleDecimal.
■ value2
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
The first OracleDecimal.
■ value2
The 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
The first OracleDecimal.
■ value2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
NotEquals
This method determines if two OracleDecimal values are not equal.
Declaration
// C#
public static bool NotEquals(OracleDecimal value1, OracleDecimal value2);
Parameters
■ value1
The first OracleDecimal.
■ value2
The 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Add
This method adds two OracleDecimal structures.
Declaration
// C#
public static OracleDecimal Add(OracleDecimal val1, OracleDecimal val2);
Parameters
■ val1
The first OracleDecimal.
■ val2
The 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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 or not 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);
// Prints 5.56
Console.WriteLine(dec2.ToString());
// Prints 5.55
Console.WriteLine(dec3.ToString());
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
■ 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);
// Prints 555.67
Console.WriteLine(dec2.ToString());
// Prints 556
Console.WriteLine(dec3.ToString());
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Divide
This method divides one OracleDecimal value by another.
Declaration
// C#
public static OracleDecimal Divide(OracleDecimal val1, OracleDecimal val2);
Parameters
■ val1
An OracleDecimal.
■ val2
An OracleDecimal.
Return Value
A new 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
An OracleDecimal structure.
Return Value
An OracleDecimal structure that has the greater value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
Return Value
An OracleDecimal.
Remarks
If either argument has a null value, the returned OracleDecimal has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
Return Value
A new 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
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);
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
{
static void Main(string[] args)
{
OracleDecimal dec1 = new OracleDecimal(555.6666);
// Prints 556
Console.WriteLine(dec2.ToString());
// Prints 555.7
Console.WriteLine(dec3.ToString());
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on
page 1-9"Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
Remarks
If either argument has a null value, the returned OracleDecimal has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Log
Log returns the supplied OracleDecimal structure with its value set to the logarithm
of the supplied OracleDecimal structure.
Overload List:
■ Log(OracleDecimal)
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ 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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Acos
This method returns an angle in radians 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 radians.
Remarks
If either argument has a null value, the returned OracleDecimal has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Asin
This method returns an angle in radians 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 radians.
Remarks
If either argument has a null value, the returned OracleDecimal has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Atan
This method returns an angle in radians 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 radians.
Remarks
If the argument has a null value, the returned OracleDecimal has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Atan2
This method returns an angle in radians 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 radians.
Remarks
If either argument has a null value, the returned OracleDecimal has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Cos
This method returns the cosine of the supplied angle in radians.
Declaration
// C#
public static OracleDecimal Cos(OracleDecimal val);
Parameters
■ val
An OracleDecimal structure that represents an angle in radians.
Return Value
An OracleDecimal instance.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Sin
This method returns the sine of the supplied angle in radians.
Declaration
// C#
public static OracleDecimal Sin(OracleDecimal val);
Parameters
■ val
An OracleDecimal structure.
Return Value
An OracleDecimal structure that represents an angle in radians.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Tan
This method returns the tangent of the supplied angle in radians.
Declaration
// C#
public static OracleDecimal Tan(OracleDecimal val);
Parameters
■ val
An OracleDecimal structure that represents an angle in radians.
Return Value
An OracleDecimal instance.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Cosh
This method returns the hyperbolic cosine of the supplied angle in radians.
Declaration
// C#
public static OracleDecimal Cosh(OracleDecimal val);
Parameters
■ val
An OracleDecimal structure that represents an angle in radians.
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
Sinh
This method returns the hyperbolic sine of the supplied angle in radians.
Declaration
// C#
public static OracleDecimal Sinh(OracleDecimal val);
Parameters
■ val
An OracleDecimal structure that represents an angle in radians.
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
Tanh
This method returns the hyperbolic tangent of the supplied angle in radians.
Declaration
// C#
public static OracleDecimal Tanh(OracleDecimal val);
Parameters
■ val
An OracleDecimal structure that represents an angle in radians.
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
operator +
This method adds two OracleDecimal values.
Declaration
// C#
public static OracleDecimal operator + (OracleDecimal val1, OracleDecimal val2);
Parameters
■ val1
The first OracleDecimal.
■ val2
The second OracleDecimal.
Return Value
An 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
operator /
This method divides one OracleDecimal value by another.
Declaration
/ C#
public static OracleDecimal operator / (OracleDecimal val1, OracleDecimal val2)
Parameters
■ val1
The first OracleDecimal.
■ val2
The second OracleDecimal.
Return Value
An 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
operator ==
This method determines if two OracleDecimal values are equal.
Declaration
// C#
public static bool operator == (OracleDecimal val1, OracleDecimal val2);
Parameters
■ val1
The first OracleDecimal.
■ val2
The second OracleDecimal.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
The first OracleDecimal.
■ val2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
operator >=
This method determines if the first of two OracleDecimal values is greater than or
equal to the second.
Declaration
// C#
public static bool operator >= (OracleDecimal val1, OracleDecimal val2);
Parameters
■ val1
The first OracleDecimal.
■ val2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
The first OracleDecimal.
■ val2
The 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
The first OracleDecimal.
■ val2
The 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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
The first OracleDecimal.
■ val2
The 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
operator *
This method multiplies two OracleDecimal structures.
Declaration
// C#
public static OracleDecimal operator * (OracleDecimal val1, OracleDecimal val2);
Parameters
■ val1
The first OracleDecimal.
■ val2
The second 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
operator -
This method subtracts one OracleDecimal structure from another.
Declaration
// C#
public static OracleDecimal operator - (OracleDecimal val1, OracleDecimal val2);
Parameters
■ val1
The first OracleDecimal.
■ val2
The second 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
operator%
This method returns a new OracleDecimal structure with its value set to the
modulus of two OracleDecimal structures.
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Declaration
// C#
public static implicit operator OracleDecimal(decimal val);
Parameters
■ val
A decimal value.
Return Value
An OracleDecimal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Declaration
// C#
public static implicit operator OracleDecimal(int val);
Parameters
■ val
An int value.
Return Value
An OracleDecimal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
OracleDecimal Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Format
This property specifies the format for ToString().
Declaration
// C#
public string Format {get; set;}
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
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
IsInt
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
IsNull
This property indicates whether or not the current instance has a null value.
Declaration
// C#
Property Value
A bool value that returns true if the current instance has a null value; otherwise,
returns false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
IsPositive
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
IsZero
This property indicates whether or not 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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 14-65 for further information.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
Equals
Overrides Object
This method determines whether or not an object is an instance of OracleDecimal,
and whether or not 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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
ToDouble
This method returns the double representation of the current instance.
Declaration
// C#
public double ToDouble();
Return Value
A double.
Exceptions
OverFlowException - The double cannot represent the current instance.
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleDecimal Members
■ OracleDecimal Structure
ToString
Overrides Object
This method returns the string representation of the current instance.
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-9
■ OracleDecimal Members
■ OracleDecimal Structure
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
OracleIntervalDS Structure
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleIntervalDS
Declaration
// ADO.NET 2.0: C#
public struct OracleIntervalDS : IComparable, INullable, IXmlSerializable
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);
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Members
■ OracleIntervalDS Constructors
■ OracleIntervalDS Static Fields
■ OracleIntervalDS Static Methods
■ OracleIntervalDS Static Operators
■ OracleIntervalDS Type Conversions
■ OracleIntervalDS Properties
■ OracleIntervalDS Methods
OracleIntervalDS Members
OracleIntervalDS Constructors
OracleIntervalDS constructors are listed in Table 14–48
OracleIntervalDS Properties
The OracleIntervalDS properties are listed in Table 14–53.
OracleIntervalDS Methods
The OracleIntervalDS methods are listed in Table 14–54.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
OracleIntervalDS Constructors
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
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-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
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.
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
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-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
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
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-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
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
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
MinValue
This static field represents the minimum value for an OracleIntervalDS structure.
Declaration
// C#
public static readonly OracleIntervalDS MinValue;
Remarks
Minimum values:
■ Day: -999999999
■ hour: -23
■ minute: -59
■ second: -59
■ nanosecond: -999999999
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Null
This static field represents a null value that can be assigned to an
OracleIntervalDS instance.
Declaration
// C#
public static readonly OracleIntervalDS Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
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-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Equals
This static method determines whether or not two OracleIntervalDS values are
equal.
Declaration
// C#
public static bool Equals(OracleIntervalDS val1, OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
If the two OracleIntervalDS structures represent the same time interval, returns
true; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
GreaterThan
This static method determines whether or not the first of two OracleIntervalDS
values is greater than the second.
Declaration
// C#
public static bool GreaterThan(OracleIntervalDS val1, OracleIntervalDS
val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the first of two OracleIntervalDS values is greater than the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
GreaterThanOrEqual
This static method determines whether or not the first of two OracleIntervalDS
values is greater than or equal to the second.
Declaration
// C#
public static bool GreaterThanOrEqual(OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the first of two OracleIntervalDS values is greater than or equal to
the second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
LessThan
This static method determines whether or not the first of two OracleIntervalDS
values is less than the second.
Declaration
// C#
public static bool LessThan(OracleIntervalDS val1, OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the first of two OracleIntervalDS values is less than the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
LessThanOrEqual
This static method determines whether or not the first of two OracleIntervalDS
values is less than or equal to the second.
Declaration
// C#
public static bool LessThanOrEqual(OracleIntervalDS val1, OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the first of two OracleIntervalDS values is less than or equal to the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
NotEquals
This static method determines whether or not two OracleIntervalDS values are not
equal.
Declaration
// C#
public static bool NotEquals(OracleIntervalDS val1, OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if two OracleIntervalDS values are not equal; otherwise, returns
false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Parse
This static method returns an OracleIntervalDS instance and sets its value for time
interval using a string.
Declaration
// C#
public static OracleIntervalDS Parse(string intervalStr);
Parameters
■ intervalStr
A string representing the Oracle INTERVAL DAY TO SECOND.
Return Value
Returns an OracleIntervalDS instance representing the time interval from the
supplied string.
Exceptions
ArgumentException - The intervalStr parameter is not in the valid format or
intervalStr has an invalid value.
ArgumentNullException - The intervalStr parameter is null.
Remarks
The value specified in 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
SetPrecision
This static method returns a new instance of an OracleIntervalDS with the
specified day precision and fractional second precision.
Declaration
// C#
public static OracleIntervalDS SetPrecision(OracleIntervalDS value1,
int dayPrecision, int fracSecPrecision);
Parameters
■ value1
An OracleIntervalDS structure.
■ dayPrecision
The day precision provided. Range of day precision is (0 to 9).
■ fracSecPrecision
The fractional second precision provided. Range of fractional second precision is
(0 to 9).
Return Value
An OracleIntervalDS instance.
Exceptions
ArgumentOutOfRangeException - An argument value is out of the specified range.
Remarks
Depending on the value specified in the supplied dayPrecision, 0 or more leading
zeros are displayed in the string returned by ToString().
The value specified in the supplied fracSecPrecision is used to perform a
rounding off operation on the supplied OracleIntervalDS value. Depending on
this value, 0 or more trailing zeros are displayed in the string returned by
ToString().
Example
The OracleIntervalDS with a value of "1 2:3:4.99" results in the string "001
2:3:4.99000" when SetPrecision() is called, with the day precision set to 3 and
fractional second precision set to 5.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator +
This static operator adds two OracleIntervalDS values.
Declaration
// C#
public static OracleIntervalDS operator + (OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
An OracleIntervalDS.
Remarks
If either argument has a null value, the returned OracleIntervalDS structure has a
null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator ==
This static operator determines if two OracleIntervalDS values are equal.
Declaration
// C#
public static bool operator == (OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the two OracleIntervalDS values are the same; otherwise returns
false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator >
This static operator determines if the first of two OracleIntervalDS values is
greater than the second.
Declaration
// C#
public static bool operator > (OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if one OracleIntervalDS value is greater than another; otherwise,
returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator >=
This static operator determines if the first of two OracleIntervalDS values is
greater than or equal to the second.
Declaration
// C#
public static bool operator >= (OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the first of two OracleIntervalDS values is greater than or equal to
the second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator !=
This static operator determines if the two OracleIntervalDS values are not equal.
Declaration
// C#
public static bool operator != (OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the two OracleIntervalDS values are not equal; otherwise, returns
false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator <
This static operator determines if the first of two OracleIntervalDS values is less
than the second.
Declaration
// C#
public static bool operator < (OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the first of two OracleIntervalDS values is less than the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator <=
This static operator determines if the first of two OracleIntervalDS values is less
than or equal to the second.
Declaration
// C#
public static bool operator <= (OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
Returns true if the first of two OracleIntervalDS values is less than or equal to the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator -
This static operator subtracts one OracleIntervalDS structure from another.
Declaration
// C#
public static OracleIntervalDS operator - (OracleIntervalDS val1,
OracleIntervalDS val2);
Parameters
■ val1
The first OracleIntervalDS.
■ val2
The second OracleIntervalDS.
Return Value
An OracleIntervalDS structure.
Remarks
If either argument has a null value, the returned OracleIntervalDS structure has a
null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator -
This static operator negates the supplied OracleIntervalDS structure.
Declaration
// C#
public static OracleIntervalDS operator - (OracleIntervalDS val);
Parameters
■ val
An OracleIntervalDS.
Return Value
An OracleIntervalDS structure.
Remarks
If the supplied OracleIntervalDS structure has a null value, the returned
OracleIntervalDS structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator *
This static operator multiplies an OracleIntervalDS value by a number.
Declaration
// C#
public static OracleIntervalDS operator * (OracleIntervalDS val1,
int multiplier);
Parameters
■ val1
The first OracleIntervalDS.
■ multiplier
A multiplier.
Return Value
A new OracleIntervalDS instance.
Remarks
If the OracleIntervalDS structure has a null value, the returned
OracleIntervalDS structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
operator /
This static operator divides an OracleIntervalDS value by a number.
Declaration
// C#
public static OracleIntervalDS operator / (OracleIntervalDS val1,
int divisor);
Parameters
■ val1
The first OracleIntervalDS.
■ divisor
A divisor.
Return Value
An OracleIntervalDS structure.
Remarks
If the OracleIntervalDS structure has a null value, the returned
OracleIntervalDS structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Declaration
// C#
public static explicit operator TimeSpan(OracleIntervalDS val);
Parameters
■ val
An OracleIntervalDS instance.
Return Value
A TimeSpan structure.
Exceptions
OracleNullValueException - The OracleIntervalDS structure has a null
value.
Remarks
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Declaration
// C#
public static explicit operator OracleIntervalDS (string intervalStr);
Parameters
■ intervalStr
A string representation of an Oracle INTERVAL DAY TO SECOND.
Return Value
An OracleIntervalDS structure.
Exceptions
ArgumentException - The supplied intervalStr parameter is not in the correct
format or has an invalid value.
ArgumentNullException - The intervalStr parameter is null.
Remarks
The returned OracleIntervalDS structure contains the same time interval
represented by the supplied intervalStr. 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Declaration
// C#
public static implicit operator OracleIntervalDS(TimeSpan val);
Parameters
■ val
A TimeSpan instance.
Return Value
An OracleIntervalDS structure.
Remarks
The returned OracleIntervalDS structure contains the same days, hours, seconds,
and milliseconds as the supplied TimeSpan val.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
OracleIntervalDS Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
BinData
This property returns an array of bytes that represents the Oracle INTERVAL DAY TO
SECOND in Oracle internal format.
Declaration
// C#
public byte[] BinData {get;}
Property Value
A byte array that represents an Oracle INTERVAL DAY TO SECOND in Oracle internal
format.
Exceptions
OracleNullValueException - The current instance has a null value.
Remarks
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Days
This property gets the days component of an OracleIntervalDS.
Declaration
// C#
public int Days {get;}
Property Value
An int representing the days component.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Hours
This property gets the hours component of an OracleIntervalDS.
Declaration
// C#
public int Hours {get;}
Property Value
An int representing the hours component.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
IsNull
This property indicates whether or not the current instance has a null value.
Declaration
// C#
Property Value
Returns true if the current instance has a null value; otherwise, returns false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Milliseconds
This property gets the milliseconds component of an OracleIntervalDS.
Declaration
// C#
public double Milliseconds {get;}
Property Value
A double that represents milliseconds component.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Minutes
This property gets the minutes component of an OracleIntervalDS.
Declaration
// C#
public int Minutes {get;}
Property Value
A int that represents minutes component.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Nanoseconds
This property gets the nanoseconds component of an OracleIntervalDS.
Declaration
// C#
public int Nanoseconds {get;}
Property Value
An int that represents nanoseconds component.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Seconds
This property gets the seconds component of an OracleIntervalDS.
Declaration
// C#
public int Seconds {get;}
Property Value
An int that represents seconds component.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
TotalDays
This property returns the total number, in days, that represent the time period in the
OracleIntervalDS structure.
Declaration
// C#
public double TotalDays {get;}
Property Value
A double that represents the total number of days.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Value
This property specifies the time interval that is stored in the OracleIntervalDS
structure.
Declaration
// C#
public TimeSpan Value {get;}
Property Value
A time interval.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
OracleIntervalDS Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
CompareTo
This method compares the current OracleIntervalDS 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 to.
Return Value
The method returns:
■ Less than zero: if the current OracleIntervalDS represents a shorter time
interval than obj.
■ Zero: if the current OracleIntervalDS and obj represent the same time
interval.
■ Greater than zero: if the current OracleIntervalDS represents a longer time
interval than obj.
Implements
IComparable
Exceptions
ArgumentException - The obj parameter is not of type OracleIntervalDS.
Remarks
The following rules apply to the behavior of this method.
■ The comparison must be between OracleIntervalDSs. For example, comparing
an OracleIntervalDS instance with an OracleBinary instance is not allowed.
When an OracleIntervalDS is compared with a different type, an
ArgumentException is thrown.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
Equals
This method determines whether or not the specified object has the same time
interval as the current instance.
Declaration
// C#
public override bool Equals(object obj);
Parameters
■ obj
The specified object.
Return Value
Returns true if obj is of type OracleIntervalDS and has the same time interval as
the current instance; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalDS that has a value compares greater than an
OracleIntervalDS that has a null value.
■ Two OracleIntervalDSs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
GetHashCode
Overrides Object
This method returns a hash code for the OracleIntervalDS instance.
Declaration
// C#
public override int GetHashCode();
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
ToString
Overrides Object
This method converts the current OracleIntervalDS structure to a string.
Declaration
// C#
public override string ToString();
Return Value
Returns a string.
Remarks
If the current instance has a null value, the returned string contains "null".
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalDS Structure
■ OracleIntervalDS Members
OracleIntervalYM Structure
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleIntervalYM
Declaration
// C#
public struct OracleIntervalYM : 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 OracleIntervalYMSample
{
static void Main()
{
OracleIntervalYM iYMMax = OracleIntervalYM.MaxValue;
double totalYears = iYMMax.TotalYears;
totalYears -= 1;
OracleIntervalYM iYMMax_1 = new OracleIntervalYM(totalYears);
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Members
■ OracleIntervalYM Constructors
■ OracleIntervalYM Static Fields
■ OracleIntervalYM Static Methods
■ OracleIntervalYM Static Operators
■ OracleIntervalYM Type Conversions
■ OracleIntervalYM Properties
■ OracleIntervalYM Methods
OracleIntervalYM Members
OracleIntervalYM Constructors
OracleIntervalYM constructors are listed in Table 14–61
OracleIntervalYM Properties
The OracleIntervalYM properties are listed in Table 14–66.
OracleIntervalYM Methods
The OracleIntervalYM methods are listed in Table 14–67.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
OracleIntervalYM Constructors
Overload List:
■ OracleIntervalYM(long)
This method creates a new instance of the OracleIntervalYM structure using
the supplied total number of months for a period of time.
■ OracleIntervalYM(string)
This method creates a new instance of the OracleIntervalYM structure and sets
its value using the supplied string.
■ OracleIntervalYM(double)
This method creates a new instance of the OracleIntervalYM structure and sets
its value using the total number of years.
■ OracleIntervalYM(int, int)
This method creates a new instance of the OracleIntervalYM structure and sets
its value using years and months.
■ OracleIntervalYM(byte[ ])
This method creates a new instance of the OracleIntervalYM structure and sets
its value to the provided byte array, which is in an internal Oracle INTERVAL DAY
TO SECOND format.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
OracleIntervalYM(long)
This method creates a new instance of the OracleIntervalYM structure using the
supplied total number of months for a period of time.
Declaration
// C#
public OracleIntervalYM (long totalMonths);
Parameters
■ totalMonths
The number of total months for a time interval. Range is -12,000,000,000 <
totalMonths < 12,000,000,000.
Exceptions
ArgumentOutOfRangeException - The totalMonths parameter is out of the
specified range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
OracleIntervalYM(string)
This method creates a new instance of the OracleIntervalYM structure and sets its
value using the supplied string.
Declaration
// C#
public OracleIntervalYM (string intervalStr);
Parameters
■ intervalStr
A string representing the Oracle INTERVAL YEAR TO MONTH.
Remarks
The value specified in the supplied intervalStr must be in Year-Month format.
Exceptions
ArgumentException - The intervalStr parameter is not in the valid format or
intervalStr has an invalid value.
ArgumentNullException - The intervalStr parameter is null.
Example
"1-2" means 1 year and 2 months.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
OracleIntervalYM(double)
This method creates a new instance of the OracleIntervalYM structure and sets its
value using the total number of years.
Declaration
// C#
public OracleIntervalYM (double totalYears);
Parameters
■ totalYears
Number of total years. Range is -1,000,000,000 < totalYears > 1,000,000,000.
Exceptions
ArgumentOutOfRangeException - The totalYears parameter is out of the
specified range.
ArgumentException - The totalYears parameter cannot be used to construct a
valid OracleIntervalYM.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
OracleIntervalYM(int, int)
This method creates a new instance of the OracleIntervalYM structure and sets its
value using years and months.
Declaration
// C#
public OracleIntervalYM (int years, int months);
Parameters
■ years
Number of years. Range of year is (-999,999,999 to 999,999,999).
■ months
Number of months. Range of month is (-11 to 11).
Remarks
The sign of all the arguments must be the same.
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 OracleIntervalYM.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
OracleIntervalYM(byte[ ])
This method creates a new instance of the OracleIntervalYM structure and sets its
value to the provided byte array, which is in an internal Oracle INTERVAL DAY TO
SECOND format.
Declaration
// C#
public OracleIntervalYM (byte[] bytes);
Parameters
■ bytes
A byte array that is in an internal Oracle INTERVAL YEAR TO MONTH format.
Exceptions
ArgumentException - The supplied byte array is not in an internal Oracle
INTERVAL YEAR TO MONTH format or the supplied byte array has an invalid value.
ArgumentNullException - bytes is null.
Remarks
The supplied byte array must be in an internal Oracle INTERVAL YEAR TO MONTH
format.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
MaxValue
This static field represents the maximum value for an OracleIntervalYM structure.
Declaration
// C#
public static readonly OracleIntervalYM MaxValue;
Remarks
Year is 999999999 and Month is 11.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
MinValue
This static field represents the minimum value for an OracleIntervalYM structure.
Declaration
// C#
public static readonly OracleIntervalYM MinValue;
Remarks
Year is -999999999 and Month is -11.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Null
This static field represents a null value that can be assigned to an
OracleIntervalYM instance.
Declaration
// C#
public static readonly OracleIntervalYM Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Zero
This static field represents a zero value for an OracleIntervalYM structure.
Declaration
// C#
public static readonly OracleIntervalDS Zero;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Equals
This static method determines whether or not two OracleIntervalYM values are
equal.
Declaration
// C#
public static bool Equals(OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
An OracleIntervalYM structure.
■ val2
An OracleIntervalYM structure.
Return Value
Returns true if two OracleIntervalYM values represent the same time interval,
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
GreaterThan
This static method determines whether or not the first of two OracleIntervalYM
values is greater than the second.
Declaration
// C#
public static bool GreaterThan(OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if the first of two OracleIntervalYM values is greater than the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
GreaterThanOrEqual
This static method determines whether or not the first of two OracleIntervalYM
values is greater than or equal to the second.
Declaration
// C#
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if the first of two OracleIntervalYM values is greater than or equal to
the second; otherwise returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
LessThan
This static method determines whether or not the first of two OracleIntervalYM
values is less than the second.
Declaration
// C#
public static bool LessThan(OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if the first of two OracleIntervalYM values is less than the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
LessThanOrEqual
This static method determines whether or not the first of two OracleIntervalYM
values is less than or equal to the second.
Declaration
// C#
public static bool LessThanOrEqual(OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if the first of two OracleIntervalYM values is less than or equal to the
second. Returns false otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
NotEquals
This static method determines whether two OracleIntervalYM values are not
equal.
Declaration
// C#
public static bool NotEquals(OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if two OracleIntervalYM values are not equal. Returns false
otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Parse
This static method returns an OracleIntervalYM structure and sets its value for
time interval using a string.
Declaration
// C#
public static OracleIntervalYM Parse (string intervalStr);
Parameters
■ intervalStr
A string representing the Oracle INTERVAL YEAR TO MONTH.
Return Value
Returns an OracleIntervalYM structure.
Exceptions
ArgumentException - The intervalStr parameter is not in the valid format or
intervalStr has an invalid value.
ArgumentNullException - The intervalStr parameter is null.
Remarks
The value specified in the supplied intervalStr must be in the Year-Month format.
Example
"1-2" means 1 year and 2 months.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
SetPrecision
This static method returns a new instance of an OracleIntervalYM with the
specified year precision.
Declaration
// C#
public static OracleIntervalYM SetPrecision(OracleIntervalYM value1,
int yearPrecision);
Parameters
■ value1
An OracleIntervalYM structure.
■ yearPrecision
The year precision provided. Range of year precision is (0 to 9).
Return Value
An OracleIntervalDS instance.
Exceptions
ArgumentOutOfRangeException - yearPrecision is out of the specified range.
Remarks
Depending on the value specified in the supplied yearPrecision, 0 or more leading
zeros are displayed in the string returned by ToString().
Example
An OracleIntervalYM with a value of "1-2" results in the string "001-2" when
SetPrecision() is called with the year precision set to 3.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator +
This static operator adds two OracleIntervalYM values.
Declaration
// C#
public static OracleIntervalYM operator + (OracleIntervalYM val1,
OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
OracleIntervalYM
Remarks
If either argument has a null value, the returned OracleIntervalYM structure has a
null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator ==
This static operator determines if two OracleIntervalYM values are equal.
Declaration
// C#
public static bool operator == (OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if they are equal; otherwise returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator >
This static operator determines if the first of two OracleIntervalYM values is
greater than the second.
Declaration
// C#
public static bool operator > (OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if one OracleIntervalYM value is greater than another; otherwise,
returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator >=
This static operator determines if the first of two OracleIntervalYM values is
greater than or equal to the second.
Declaration
// C#
public static bool operator >= (OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if one OracleIntervalYM value is greater than or equal to another;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator !=
This static operator determines whether two OracleIntervalYM values are not
equal.
Declaration
// C#
public static bool operator != (OracleIntervalYM val1, OracleIntervalYM val2)
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if two OracleIntervalYM values are not equal; otherwise, returns
false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator <
This static operator determines if the first of two OracleIntervalYM values is less
than the second.
Declaration
// C#
public static bool operator < (OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if the first of two OracleIntervalYM values is less than the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator <=
This static operator determines if the first of two OracleIntervalYM values is less
than or equal to the second.
Declaration
// C#
public static bool operator <= (OracleIntervalYM val1, OracleIntervalYM val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
Returns true if the first of two OracleIntervalYM values is less than or equal to the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator -
This static operator subtracts one OracleIntervalYM structure from another.
Declaration
// C#
public static OracleIntervalYM operator - (OracleIntervalYM val1, OracleIntervalYM
val2);
Parameters
■ val1
The first OracleIntervalYM.
■ val2
The second OracleIntervalYM.
Return Value
An OracleIntervalYM structure.
Remarks
If either argument has a null value, the returned OracleIntervalYM structure has a
null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator -
This static operator negates an OracleIntervalYM structure.
Declaration
// C#
public static OracleIntervalYM operator - (OracleIntervalYM val);
Parameters
■ val
An OracleIntervalYM.
Return Value
An OracleIntervalYM structure.
Remarks
If the supplied OracleIntervalYM structure has a null value, the returned
OracleIntervalYM structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator *
This static operator multiplies an OracleIntervalYM value by a number.
Declaration
// C#
public static OracleIntervalYM operator * (OracleIntervalYM val1, int multiplier);
Parameters
■ val1
The first OracleIntervalYM.
■ multiplier
A multiplier.
Return Value
An OracleIntervalYM structure.
Remarks
If the supplied OracleIntervalYM structure has a null value, the returned
OracleIntervalYM structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
operator /
This static operator divides an OracleIntervalYM value by a number.
Declaration
// C#
public static OracleIntervalYM operator / (OracleIntervalYM val1, int divisor);
Parameters
■ val1
The first OracleIntervalYM.
■ divisor
A divisor.
Return Value
An OracleIntervalYM structure.
Remarks
If the supplied OracleIntervalYM structure has a null value, the returned
OracleIntervalYM structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Declaration
// C#
public static explicit operator long (OracleIntervalYM val);
Parameters
■ val
An OracleIntervalYM structure.
Return Value
A long number in months.
Exceptions
OracleNullValueException - The OracleIntervalYM structure has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Declaration
// C#
public static explicit operator OracleIntervalYM (string intervalStr);
Parameters
■ intervalStr
A string representation of an Oracle INTERVAL YEAR TO MONTH.
Return Value
An OracleIntervalYM structure.
Exceptions
ArgumentException - The supplied intervalStr parameter is not in the correct
format or has an invalid value.
ArgumentNullException - The intervalStr parameter is null.
Remarks
The returned OracleIntervalDS structure contains the same time interval
represented by the supplied intervalStr. The value specified in the supplied
intervalStr must be in Year-Month format.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Declaration
// C#
public static implicit operator OracleIntervalYM (long months);
Parameters
■ months
The number of months to be converted. Range is (-999,999,999 * 12)-11 <= months
<= (999,999,999 * 12)+11.
Return Value
An OracleIntervalYM structure.
Exceptions
ArgumentOutOfRangeException - The months parameter is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
OracleIntervalYM Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
BinData
This property returns an array of bytes that represents the Oracle INTERVAL YEAR TO
MONTH in Oracle internal format.
Declaration
// C#
public byte[] BinData {get;}
Property Value
A byte array that represents an Oracle INTERVAL YEAR TO MONTH in Oracle internal
format.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
IsNull
This property indicates whether or not the value has a null value.
Declaration
// C#
Property Value
Returns true if value has a null value; otherwise, returns false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Months
This property gets the months component of an OracleIntervalYM.
Declaration
// C#
public int Months {get;}
Property Value
An int representing the months component.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
TotalYears
This property returns the total number, in years, that represents the period of time in
the current OracleIntervalYM structure.
Declaration
// C#
public double TotalYears {get;}
Property Value
A double representing the total number of years.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Value
This property gets the total number of months that is stored in the
OracleIntervalYM structure.
Declaration
// C#
public long Value {get;}
Property Value
The total number of months representing the time interval.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Years
This property gets the years component of an OracleIntervalYM.
Declaration
// C#
public int Years {get;}
Property Value
An int representing the years component.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
OracleIntervalYM Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
CompareTo
This method compares the current OracleIntervalYM 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 object.
Return Value
The method returns a number:
Less than zero: if the current OracleIntervalYM represents a shorter time interval
than obj.
Zero: if the current OracleIntervalYM and obj represent the same time interval.
Greater than zero: if the current OracleIntervalYM represents a longer time interval
than obj.
Implements
IComparable
Exceptions
ArgumentException - The obj parameter is not of type OracleIntervalYM.
Remarks
The following rules apply to the behavior of this method.
■ The comparison must be between OracleIntervalYMs. For example, comparing
an OracleIntervalYM instance with an OracleBinary instance is not allowed.
When an OracleIntervalYM is compared with a different type, an
ArgumentException is thrown.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
Equals
Overrides Object
This method determines whether or not the specified object has the same time interval
as the current instance.
Declaration
// C#
public override bool Equals(object obj);
Parameters
■ obj
The supplied object.
Return Value
Returns true if the specified object instance is of type OracleIntervalYM and has
the same time interval; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleIntervalYM that has a value compares greater than an
OracleIntervalYM that has a null value.
■ Two OracleIntervalYMs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
GetHashCode
Overrides Object
This method returns a hash code for the OracleIntervalYM instance.
Declaration
// C#
public override int GetHashCode();
Return Value
An int representing a hash code.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
ToString
Overrides Object
This method converts the current OracleIntervalYM structure to a string.
Declaration
// C#
public override string ToString();
Return Value
A string that represents the current OracleIntervalYM structure.
Remarks
If the current instance has a null value, the returned string contain "null".
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleIntervalYM Structure
■ OracleIntervalYM Members
OracleString Structure
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleString
Declaration
// ADO.NET 2.0: C#
public struct OracleString : IComparable, INullable, IXmlSerializable
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 OracleStringSample
{
static void Main()
{
// Initialize OracleString structs
OracleString string1 = new OracleString("AAA");
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Members
■ OracleString Constructors
■ OracleString Static Fields
■ OracleString Static Methods
■ OracleString Static Operators
■ OracleString Type Conversions
■ OracleString Properties
■ OracleString Methods
OracleString Members
OracleString Constructors
OracleString constructors are listed in Table 14–74
OracleString Properties
The OracleString properties are listed in Table 14–79.
OracleString Methods
The OracleString methods are listed in Table 14–80.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
OracleString Constructors
Overload List:
■ OracleString(string)
This constructor creates a new instance of the OracleString structure and sets
its value using a string.
■ OracleString(string, bool)
This constructor creates a new instance of the OracleString structure and sets
its value using a string and specifies if case is ignored in comparison.
■ OracleString(byte [ ], bool)
This constructor creates a new instance of the OracleString structure and sets
its value using a byte array and specifies if the supplied byte array is Unicode
encoded.
■ OracleString(byte [ ], bool, bool)
This constructor creates a new instance of the OracleString structure and sets
its value using a byte array and specifies the following: if the supplied byte array
is Unicode encoded and if case is ignored in comparison.
■ OracleString(byte [ ], int, int, bool)
This constructor creates a new instance of the OracleString structure and sets
its value using a byte array, and specifies the following: the starting index in the
byte array, the number of bytes to copy from the byte array, and if the supplied
byte array is Unicode encoded.
■ OracleString(byte [ ], int, int, bool, bool)
This constructor creates a new instance of the OracleString structure and sets
its value using a byte array, and specifies the following: the starting index in the
byte array, the number of bytes to copy from the byte array, if the supplied byte
array is Unicode encoded, and if case is ignored in comparison.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
OracleString(string)
This constructor creates a new instance of the OracleString structure and sets its
value using a string.
Declaration
// C#
public OracleString(string data);
Parameters
■ data
A string value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
OracleString(string, bool)
This constructor creates a new instance of the OracleString structure and sets its
value using a string and specifies if case is ignored in comparison.
Declaration
// C#
public OracleString(string data, bool isCaseIgnored);
Parameters
■ data
A string value.
■ isCaseIgnored
Specifies if case is ignored in comparison. Specifies true if case is to be ignored;
otherwise, specifies false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
OracleString(byte [ ], bool)
This constructor creates a new instance of the OracleString structure and sets its
value using a byte array and specifies if the supplied byte array is Unicode encoded.
Declaration
// C#
public OracleString(byte[] data, bool fUnicode);
Parameters
■ data
Byte array data for the new OracleString.
■ fUnicode
Specifies if the supplied data is Unicode encoded. Specifies true if Unicode
encoded; otherwise, false.
Exceptions
ArgumentNullException - The data parameter is null.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Declaration
// C#
public OracleString(byte[] data, bool fUnicode, bool isCaseIgnored);
Parameters
■ data
Byte array data for the new OracleString.
■ fUnicode
Specifies if the supplied data is Unicode encoded. Specifies true if Unicode
encoded; otherwise, false.
■ isCaseIgnored
Specifies if case is ignored in comparison. Specifies true if case is to be ignored;
otherwise, specifies false.
Exceptions
ArgumentNullException - The data parameter is null.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Declaration
// C#
public OracleString(byte[] data, int index, int count, bool fUnicode);
Parameters
■ data
Byte array data for the new OracleString.
■ index
Exceptions
ArgumentNullException - The data parameter is null.
ArgumentOutOfRangeException - The count parameter is less than zero.
IndexOutOfRangeException - The index parameter is greater than or equal to the
length of data or less than zero.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Declaration
// C#
public OracleString(byte[] data, int index, int count, bool fUnicode,
bool isCaseIgnored);
Parameters
■ data
Byte array data for the new OracleString.
■ index
The starting index to copy from data.
■ count
The number of bytes to copy.
■ fUnicode
Specifies if the supplied data is Unicode encoded. Specifies true if Unicode
encoded; otherwise, false.
■ isCaseIgnored
Specifies if case is ignored in comparison. Specifies true if case is to be ignored;
otherwise, specifies false.
Exceptions
ArgumentNullException - The data parameter is null.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Null
This static field represents a null value that can be assigned to an instance of the
OracleString structure.
Declaration
// C#
public static readonly OracleString Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Concat
This static method concatenates two OracleString instances and returns a new
OracleString instance that represents the result.
Declaration
// C#
public static OracleString Concat(OracleString str1, OracleString str2);
Parameters
■ str1
The first OracleString.
■ str2
The second OracleString.
Return Value
An OracleString.
Remarks
If either argument has a null value, the returned OracleString structure has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Equals
Overloads Object
This static method determines whether or not the two OracleStrings being
compared are equal.
Declaration
// C#
public static bool Equals(OracleString str1, OracleString str2);
Parameters
■ str1
The first OracleString.
■ str2
The second OracleString.
Return Value
Returns true if the two OracleStrings being compared are equal; returns false
otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
GreaterThan
This static method determines whether or not the first of two OracleString values
is greater than the second.
Declaration
// C#
public static bool GreaterThan(OracleString str1, OracleString str2);
Parameters
■ str1
The first OracleString.
■ str2
The second OracleString.
Return Value
Returns true if the first of two OracleStrings is greater than the second; otherwise,
returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
GreaterThanOrEqual
This static method determines whether or not the first of two OracleString values
is greater than or equal to the second.
Declaration
// C#
public static bool GreaterThanOrEqual(OracleString str1,
OracleString str2);
Parameters
■ str1
The first OracleString.
■ str2
The second OracleString.
Return Value
Returns true if the first of two OracleStrings is greater than or equal to the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
LessThan
This static method determines whether or not the first of two OracleString values
is less than the second.
Declaration
// C#
public static bool LessThan(OracleString str1, OracleString str2);
Parameters
■ str1
The first OracleString.
■ str2
The second OracleString.
Return Value
Returns true if the first is less than the second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
LessThanOrEqual
This static method determines whether or not the first of two OracleString values
is less than or equal to the second.
Declaration
// C#
public static bool LessThanOrEqual(OracleString str1, OracleString str2);
Parameters
■ str1
The first OracleString.
■ str2
Return Value
Returns true if the first is less than or equal to the second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
NotEquals
This static method determines whether two OracleString values are not equal.
Declaration
// C#
public static bool NotEquals(OracleString str1, OracleString str2);
Parameters
■ str1
The first OracleString.
■ str2
The second OracleString.
Return Value
Returns true if the two OracleString instances are not equal; otherwise, returns
false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
operator +
This static operator concatenates two OracleString values.
Declaration
// C#
public static OracleString operator + (OracleString value1, OracleString value2);
Parameters
■ value1
The first OracleString.
■ value2
The second OracleString.
Return Value
An OracleString.
Remarks
If either argument has a null value, the returned OracleString structure has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
operator ==
This static operator determines if two OracleString values are equal.
Declaration
// C#
public static bool operator == (OracleString value1, OracleString value2);
Parameters
■ value1
The first OracleString.
■ value2
The second OracleString.
Return Value
Returns true if two OracleString values are equal; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
operator >
This static operator determines if the first of two OracleString values is greater
than the second.
Declaration
// C#
public static bool operator > (OracleString value1, OracleString value2);
Parameters
■ value1
The first OracleString.
■ value2
The second OracleString.
Return Value
Returns true if the first of two OracleString values is greater than the second;
otherwise returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
operator >=
This static operator determines if the first of two OracleString values is greater
than or equal to the second.
Declaration
// C#
public static bool operator >= (OracleString value1, OracleString value2);
Parameters
■ value1
The first OracleString.
■ value2
The second OracleString.
Return Value
Returns true if the first of two OracleString values is greater than or equal to the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
operator !=
This static operator determines if two OracleString values are not equal.
Declaration
// C#
public static bool operator != (OracleString value1, OracleString value2);
Parameters
■ value1
The first OracleString.
■ value2
The second OracleString.
Return Value
Returns true if two OracleString values are not equal; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
operator <
This static operator determines if the first of two OracleStrings is less than the
second.
Declaration
// C#
public static bool operator < (OracleString value1, OracleString value2);
Parameters
■ value1
The first OracleString.
■ value2
The second OracleString.
Return Value
Returns true if the first of two OracleStrings is less than the second; otherwise,
returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
operator <=
This static operator determines if the first of two OracleString values is less than or
equal to the second.
Declaration
// C#
public static bool operator <= (OracleString value1, OracleString value1);
Parameters
■ value1
The first OracleString.
■ value2
The second OracleString.
Return Value
Returns true if the first of two OracleString values is less than or equal to the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Declaration
//C#
public static explicit operator string (OracleString value1);
Parameters
■ value1
The supplied OracleString.
Return Value
string
Exceptions
OracleNullValueException - The OracleString structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Declaration
// C#
public static implicit operator OracleString (string value1);
Parameters
■ value1
Return Value
An OracleString.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
OracleString Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
IsCaseIgnored
This property indicates whether or not case should be ignored when performing string
comparison.
Declaration
//C#
public bool IsCaseIgnored {get;set;}
Property Value
Returns true if string comparison must ignore case; otherwise false.
Remarks
Default value is true.
Example
// C#
using System;
using Oracle.DataAccess.Types;
class IsCaseIgnoredSample
{
static void Main()
{
OracleString string1 = new OracleString("aAaAa");
OracleString string2 = new OracleString("AaAaA");
// Same; Prints 0
Console.WriteLine(string1.CompareTo(string2));
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
IsNull
This property indicates whether or not the current instance contains a null value.
Declaration
// C#
public bool IsNull {get;}
Property Value
Returns true if the current instance contains has a null value; otherwise, returns
false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Item
This property obtains the particular character in an OracleString using an index.
Declaration
// C#
public char Item {get;}
Property Value
A char value.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Length
This property returns the length of the OracleString.
Declaration
// C#
public int Length {get;}
Property Value
A int value.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
OracleString Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Clone
This method creates a copy of an OracleString instance.
Declaration
// C#
public OracleString Clone();
Return Value
An OracleString structure.
Remarks
The cloned object has the same property values as that of the object being cloned.
Example
// C#
using System;
using Oracle.DataAccess.Types;
class CloneSample
{
static void Main()
{
OracleString str1 = new OracleString("aAaAa");
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
CompareTo
This method compares the current OracleString instance to the supplied object,
and returns an integer that represents their relative values.
Declaration
// C#
public int CompareTo(object obj);
Parameters
■ obj
The object being compared to the current instance.
Return Value
The method returns a number that is:
■ Less than zero: if the current OracleString value is less than obj.
■ Zero: if the current OracleString value is equal to obj.
■ Greater than zero: if the current OracleString value is greater than obj.
Implements
IComparable
Exceptions
ArgumentException - The obj parameter is not of type OracleString.
Remarks
The following rules apply to the behavior of this method.
■ The comparison must be between OracleStrings. For example, comparing an
OracleString instance with an OracleBinary instance is not allowed. When
an OracleString is compared with a different type, an ArgumentException is
thrown.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
Equals
This method determines whether or not supplied object is an instance of
OracleString and has the same values as the current OracleString instance.
Declaration
// C#
public override bool Equals(object obj);
Parameters
■ obj
An object being compared.
Return Value
Returns true if the supplied object is an instance of OracleString and has the same
values as the current OracleString instance; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleString that has a value is greater than an OracleString that has a
null value.
■ Two OracleStrings that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
GetHashCode
Overrides Object
This method returns a hash code for the OracleString instance.
Declaration
// C#
public override int GetHashCode();
Return Value
A number that represents the hash code.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
GetNonUnicodeBytes
This method returns an array of bytes, containing the contents of the OracleString,
in the client character set format.
Declaration
// C#
public byte[] GetNonUnicodeBytes();
Return Value
A byte array that contains the contents of the OracleString in the client character
set format.
Remarks
If the current instance has a null value, an OracleNullValueException is thrown.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
GetUnicodeBytes
This method returns an array of bytes, containing the contents of the OracleString
in Unicode format.
Declaration
// C#
public byte[] GetUnicodeBytes();
Return Value
A byte array that contains the contents of the OracleString in Unicode format.
Remarks
If the current instance has a null value, an OracleNullValueException is thrown.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
ToString
Overrides Object
This method converts the current OracleString instance to a string.
Declaration
// C#
public override string ToString();
Return Value
A string.
Remarks
If the current OracleString instance has a null value, the string contains "null".
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleString Structure
■ OracleString Members
OracleTimeStamp Structure
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleTimeStamp
Declaration
// ADO.NET 2.0: C#
public struct OracleTimeStamp : IComparable, INullable, IXmlSerializable
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 OracleTimeStampSample
{
static void Main()
{
OracleTimeStamp tsCurrent1 = OracleTimeStamp.GetSysDate();
OracleTimeStamp tsCurrent2 = DateTime.Now;
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Members
■ OracleTimeStamp Constructors
■ OracleTimeStamp Static Fields
■ OracleTimeStamp Static Methods
■ OracleTimeStamp Static Operators
■ OracleTimeStamp Static Type Conversions
■ OracleTimeStamp Properties
■ OracleTimeStamp Methods
OracleTimeStamp Members
OracleTimeStamp Constructors
OracleTimeStamp constructors are listed in Table 14–87
OracleTimeStamp Properties
The OracleTimeStamp properties are listed in Table 14–92.
OracleTimeStamp Methods
The OracleTimeStamp methods are listed in Table 14–93.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
OracleTimeStamp Constructors
Overload List:
■ OracleTimeStamp(DateTime)
This constructor creates a new instance of the OracleTimeStamp structure and
sets its value for date and time using the supplied DateTime value.
■ OracleTimeStamp(string)
This constructor creates a new instance of the OracleTimeStamp structure and
sets its value using the supplied string.
■ OracleTimeStamp(int, int, int)
This constructor creates a new instance of the OracleTimeStamp structure and
sets its value for date using year, month, and day.
■ OracleTimeStamp(int, int, int, int, int, int)
This constructor creates a new instance of the OracleTimeStamp structure and
sets its value for date and time using year, month, day, hour, minute, and second.
■ OracleTimeStamp(int, int, int, int, int, int, double)
This constructor creates a new instance of the OracleTimeStamp structure and
sets its value for date and time using year, month, day, hour, minute, second, and
millisecond.
■ OracleTimeStamp(int, int, int, int, int, int, int)
This constructor creates a new instance of the OracleTimeStamp structure and
sets its value for date and time using year, month, day, hour, minute, second, and
nanosecond.
■ OracleTimeStamp(byte [ ])
This constructor creates a new instance of the OracleTimeStamp structure and
sets its value to the provided byte array, which is in the internal Oracle
TIMESTAMP format.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
OracleTimeStamp(DateTime)
This constructor creates a new instance of the OracleTimeStamp structure and sets
its value for date and time using the supplied DateTime value.
Declaration
// C#
public OracleTimeStamp (DateTime dt);
Parameters
■ dt
The supplied DateTime value.
Exceptions
ArgumentException - The dt parameter cannot be used to construct a valid
OracleTimeStamp.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
OracleTimeStamp(string)
This constructor creates a new instance of the OracleTimeStamp structure and sets
its value using the supplied string.
Declaration
// C#
public OracleTimeStamp (string tsStr);
Parameters
■ tsStr
A string that represents an Oracle TIMESTAMP.
Exceptions
ArgumentException - The tsStr value is an invalid string representation of an
Oracle TIMESTAMP or the supplied tsStr is not in the timestamp format specified by
the OracleGlobalization.TimeStampFormat property of the thread, which
represents the Oracle NLS_TIMESTAMP_FORMAT parameter.
ArgumentNullException - The tsStr value 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 OracleTimeStampSample
{
static void Main()
{
// Set the nls_timestamp_format for the OracleTimeStamp(string)
// constructor
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
■ Oracle Database SQL Reference for further information on date
format elements
Declaration
// C#
public OracleTimeStamp(int year, int month, int day);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. 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 OracleTimeStamp (that is, the day is out of range for the month).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public OracleTimeStamp (int year, int month, int day, int hour,
int minute, int second);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. 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 OracleTimeStamp (that is, the day is out of range for the month).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public OracleTimeStamp(int year, int month, int day, int hour,
int minute, int second, double millisecond);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ milliSeconds
The milliseconds provided. Range of millisecond is (0 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 OracleTimeStamp (that is, the day is out of range for the month).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public OracleTimeStamp (int year, int month, int day, int hour,
int minute, int second, int nanosecond);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ nanosecond
The nanosecond provided. Range of nanosecond is (0 to 999999999).
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 OracleTimeStamp (that is, the day is out of range for the month).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
OracleTimeStamp(byte [ ])
This constructor creates a new instance of the OracleTimeStamp structure and sets
its value to the provided byte array, which is in the internal Oracle TIMESTAMP format.
Declaration
// C#
public OracleTimeStamp (byte[] bytes);
Parameters
■ bytes
A byte array that represents an Oracle TIMESTAMP in Oracle internal format.
Exceptions
ArgumentException - bytes is not in an internal Oracle TIMESTAMP format or
bytes is not a valid Oracle TIMESTAMP.
ArgumentNullException - bytes is null.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
MaxValue
This static field represents the maximum valid date and time for an
OracleTimeStamp structure, which is December 31, 9999 23:59:59.999999999.
Declaration
// C#
public static readonly OraTimestamp MaxValue;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
MinValue
This static field represents the minimum valid date and time for an
OracleTimeStamp structure, which is January 1, -4712 0:0:0.
Declaration
// C#
public static readonly OracleTimeStamp MinValue;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Null
This static field represents a null value that can be assigned to an instance of the
OracleTimeStamp structure.
Declaration
// C#
public static readonly OracleTimeStamp Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Equals
This static method determines if two OracleTimeStamp values are equal.
Declaration
// C#
public static bool Equals(OracleTimeStamp value1, OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if two OracleTimeStamp values are equal; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
GreaterThan
This static method determines if the first of two OracleTimeStamp values is greater
than the second.
Declaration
// C#
public static bool GreaterThan(OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if the first of two OracleTimeStamp values is greater than the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
GreaterThanOrEqual
This static method determines if the first of two OracleTimeStamp values is greater
than or equal to the second.
Declaration
// C#
public static bool GreaterThanOrEqual(OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if the first of two OracleTimeStamp values is greater than or equal to
the second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
LessThan
This static method determines if the first of two OracleTimeStamp values is less than
the second.
Declaration
// C#
public static bool LessThan(OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if the first of two OracleTimeStamp values is less than the second.
Returns false otherwise.
Remarks
The following rules apply to the behavior of this method.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
LessThanOrEqual
This static method determines if the first of two OracleTimeStamp values is less than
or equal to the second.
Declaration
// C#
public static bool LessThanOrEqual(OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if the first of two OracleTimeStamp values is less than or equal to the
second. Returns false otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
NotEquals
This static method determines if two OracleTimeStamp values are not equal.
Declaration
// C#
public static bool NotEquals(OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if two OracleTimeStamp values are not equal. Returns false
otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
GetSysDate
This static method gets an OracleTimeStamp structure that represents the current
date and time.
Declaration
// C#
public static OracleTimeStamp GetSysDate();
Return Value
An OracleTimeStamp structure that represents the current date and time.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Parse
This static method gets an OracleTimeStamp structure and sets its value using the
supplied string.
Declaration
// C#
public static OracleTimeStamp Parse(string datetime);
Parameters
■ datetime
Return Value
An OracleTimeStamp structure.
Exceptions
ArgumentException - The tsStr is an invalid string representation of an Oracle
TIMESTAMP or the supplied tsStr is not in the timestamp format specified by the
OracleGlobalization.TimeStampFormat property of the thread, which
represents the Oracle NLS_TIMESTAMP_FORMAT parameter.
ArgumentNullException - The tsStr value 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()
{
// Set the nls_timestamp_format for the Parse() method
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampFormat = "DD-MON-YYYY HH:MI:SS.FF AM";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
SetPrecision
This static method returns a new instance of an OracleTimeStamp with the specified
fractional second precision.
Declaration
// C#
public static OracleTimeStamp SetPrecision(OracleTimeStamp value1,
int fracSecPrecision);
Parameters
■ value1
The provided OracleTimeStamp object.
■ fracSecPrecision
The fractional second precision provided. Range of fractional second precision is
(0 to 9).
Return Value
An OracleTimeStamp structure with the specified fractional second precision.
Exceptions
ArgumentOutOfRangeException - fracSecPrecision is out of the specified
range.
Remarks
The value specified in the supplied fracSecPrecision is used to perform a
rounding off operation on the supplied OracleTimeStamp value. Depending on this
value, 0 or more trailing zeros are displayed in the string returned by ToString().
Example
The OracleTimeStamp with a value of "December 31, 9999 23:59:59.99" results
in the string "December 31, 9999 23:59:59.99000" when SetPrecision() is
called with the fractional second precision set to 5.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
operator +
operator+ adds the supplied object to the OracleTimeStamp and returns a new
OracleTimeStamp structure.
Overload List:
■ operator + (OracleTimeStamp, OracleIntervalDS)
This static operator adds the supplied OracleIntervalDS to the
OracleTimeStamp and returns a new OracleTimeStamp structure.
■ operator + (OracleTimeStamp, OracleIntervalYM)
This static operator adds the supplied OracleIntervalYM to the supplied
OracleTimeStamp and returns a new OracleTimeStamp structure.
■ operator + (OracleTimeStamp, TimeSpan)
This static operator adds the supplied TimeSpan to the supplied
OracleTimeStamp and returns a new OracleTimeStamp structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static operator + (OracleTimeStamp value1, OracleIntervalDS value2);
Parameters
■ value1
An OracleTimeStamp.
■ value2
An OracleIntervalDS.
Return Value
An OracleTimeStamp.
Remarks
If either parameter has a null value, the returned OracleTimeStamp has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static operator + (OracleTimeStamp value1, OracleIntervalYM value2);
Parameters
■ value1
An OracleTimeStamp.
■ value2
An OracleIntervalYM.
Return Value
An OracleTimeStamp.
Remarks
If either parameter has a null value, the returned OracleTimeStamp has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static operator + (OracleTimeStamp value1, TimeSpan value2);
Parameters
■ value1
An OracleTimeStamp.
■ value2
A TimeSpan.
Return Value
An OracleTimeStamp.
Remarks
If the OracleTimeStamp instance has a null value, the returned OracleTimeStamp
has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
operator ==
This static operator determines if two OracleTimeStamp values are equal.
Declaration
// C#
public static bool operator == (OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if they are the same; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
operator >
This static operator determines if the first of two OracleTimeStamp values is greater
than the second.
Declaration
// C#
public static bool operator > (OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if the first OracleTimeStamp value is greater than the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
operator >=
This static operator determines if the first of two OracleTimeStamp values is greater
than or equal to the second.
Declaration
// C#
public static bool operator >= (OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if the first OracleTimeStamp is greater than or equal to the second;
otherwise returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
operator !=
This static operator determines if two OracleTimeStamp values are not equal.
Declaration
// C#
public static bool operator != (OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if two OracleTimeStamp values are not equal; otherwise, returns
false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
operator <
This static operator determines if the first of two OracleTimeStamp values is less
than the second.
Declaration
// C#
public static bool operator < (OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if the first OracleTimeStamp is less than the second; otherwise,
returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
operator <=
This static operator determines if the first of two OracleTimeStamp values is less
than or equal to the second.
Declaration
// C#
public static bool operator <= (OracleTimeStamp value1,
OracleTimeStamp value2);
Parameters
■ value1
The first OracleTimeStamp.
■ value2
The second OracleTimeStamp.
Return Value
Returns true if the first OracleTimeStamp is less than or equal to the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
operator -
operator- subtracts the supplied value, from the supplied OracleTimeStamp
value, and returns a new OracleTimeStamp structure.
Overload List:
■ operator - (OracleTimeStamp, OracleIntervalDS)
This static operator subtracts the supplied OracleIntervalDS value, from the
supplied OracleTimeStamp value, and return a new OracleTimeStamp
structure.
■ operator - (OracleTimeStamp, OracleIntervalYM)
This static operator subtracts the supplied OracleIntervalYM value, from the
supplied OracleTimeStamp value, and returns a new OracleTimeStamp
structure.
■ operator - (OracleTimeStamp, TimeSpan)
This static operator subtracts the supplied TimeSpan value, from the supplied
OracleTimeStamp value, and returns a new OracleTimeStamp structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static operator - (OracleTimeStamp value1, OracleIntervalDS value2);
Parameters
■ value1
An OracleTimeStamp.
■ value2
An OracleIntervalDS instance.
Return Value
An OracleTimeStamp structure.
Remarks
If either parameter has a null value, the returned OracleTimeStamp has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static operator - (OracleTimeStamp value1, OracleIntervalYM value2);
Parameters
■ value1
An OracleTimeStamp.
■ value2
An OracleIntervalYM instance.
Return Value
An OracleTimeStamp structure.
Remarks
If either parameter has a null value, the returned OracleTimeStamp has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static operator - (OracleTimeStamp value1, TimeSpan value2);
Parameters
■ value1
An OracleTimeStamp.
■ value2
A TimeSpan instance.
Return Value
An OracleTimeStamp structure.
Remarks
If the OracleTimeStamp instance has a null value, the returned OracleTimeStamp
structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Overload List:
■ explicit operator OracleTimeStamp(OracleTimeStampLTZ)
This static type conversion operator converts an OracleTimeStampLTZ value to
an OracleTimeStamp structure.
■ explicit operator OracleTimeStamp(OracleTimeStampTZ)
This static type conversion operator converts an OracleTimeStampTZ value to
an OracleTimeStamp structure.
■ explicit operator OracleTimeStamp(string)
This static type conversion operator converts the supplied string to an
OracleTimeStamp structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static explicit operator OracleTimeStamp(OracleTimeStampLTZ value1);
Parameters
■ value1
An OracleTimeStampLTZ instance.
Return Value
The returned OracleTimeStamp contains the date and time of the
OracleTimeStampLTZ structure.
Remarks
If the OracleTimeStampLTZ structure has a null value, the returned
OracleTimeStamp structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static explicit operator OracleTimeStamp(OracleTimeStampTZ value1);
Parameters
■ value1
An OracleTimeStampTZ instance.
Return Value
The returned OracleTimeStamp contains the date and time information from
value1, but the time zone information from value1 is truncated.
Remarks
If the OracleTimeStampTZ structure has a null value, the returned
OracleTimeStamp structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
Parameters
■ tsStr
A string representation of an Oracle TIMESTAMP.
Return Value
An OracleTimeStamp.
Exceptions
ArgumentException - The tsStr is an invalid string representation of an Oracle
TIMESTAMP or the tsStr is not in the timestamp format specified by the thread's
OracleGlobalization.TimeStampFormat property, which represents the Oracle
NLS_TIMESTAMP_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.Types;
using Oracle.DataAccess.Client;
class OracleTimeStampSample
{
static void Main()
{
// Set the nls_timestamp_format for the explicit
// operator OracleTimeStamp(string)
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampFormat = "DD-MON-YYYY HH:MI:SS.FF AM";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
■ Oracle Database SQL Reference for further information on
datetime format elements
Overload List:
■ implicit operator OracleTimeStamp(OracleDate)
This static type conversion operator converts an OracleDate value to an
OracleTimeStamp structure.
■ implicit operator OracleTimeStamp(DateTime)
This static type conversion operator converts a DateTime value to an
OracleTimeStamp structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static implicit operator OracleTimeStamp (OracleDate value1);
Parameters
■ value1
An OracleDate instance.
Return Value
An OracleTimeStamp structure that contains the date and time of the OracleDate
structure, value1.
Remarks
If the OracleDate structure has a null value, the returned OracleTimeStamp
structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static implicit operator OracleTimeStamp(DateTime value);
Parameters
■ value
A DateTime instance.
Return Value
An OracleTimeStamp structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Declaration
// C#
public static explicit operator DateTime(OracleTimeStamp value1);
Parameters
■ value1
An OracleTimeStamp instance.
Return Value
A DateTime containing the date and time in the current instance.
Exceptions
OracleNullValueException - The OracleTimeStamp structure has a null value.
Remarks
The precision of the OracleTimeStamp can be lost during the conversion.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
OracleTimeStamp Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
BinData
This property returns an array of bytes that represents an Oracle TIMESTAMP in Oracle
internal format.
Declaration
// C#
public byte[] BinData {get;}
Property Value
A byte array that represents an Oracle TIMESTAMP in an internal format.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Day
This property specifies the day component of an OracleTimeStamp.
Declaration
// C#
public int Day{get;}
Property Value
A number that represents the day. Range of Day is (1 to 31).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
IsNull
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Hour
This property specifies the hour component of an OracleTimeStamp.
Declaration
// C#
public int Hour{get;}
Property Value
A number that represents the hour. Range of hour is (0 to 23).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Millisecond
This property gets the millisecond component of an OracleTimeStamp.
Declaration
// C#
public double Millisecond{get;}
Property Value
A number that represents a millisecond. Range of Millisecond is (0 to 999.999999).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Minute
This property gets the minute component of an OracleTimeStamp.
Declaration
// C#
public int Minute{get;}
Property Value
A number that represent a minute. Range of Minute is (0 to 59).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Month
This property gets the month component of an OracleTimeStamp.
Declaration
// C#
public int Month{get;}
Property Value
A number that represents a month. Range of Month is (1 to 12).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Nanosecond
This property gets the nanosecond component of an OracleTimeStamp.
Declaration
// C#
public int Nanosecond{get;}
Property Value
A number that represents a nanosecond. Range of Nanosecond is (0 to 999999999).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Second
This property gets the second component of an OracleTimeStamp.
Declaration
// C#
public int Second{get;}
Property Value
A number that represents a second. Range of Second is (0 to 59).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Value
This property specifies the date and time that is stored in the OracleTimeStamp
structure.
Declaration
// C#
public DateTime Value{get;}
Property Value
A DateTime.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Year
This property gets the year component of an OracleTimeStamp.
Declaration
// C#
public int Year{get;}
Property Value
A number that represents a year. The range of Year is (-4712 to 9999).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
OracleTimeStamp Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
AddDays
This method adds the supplied number of days to the current instance.
Declaration
// C#
public OracleTimeStamp AddDays(double days);
Parameters
■ days
The supplied number of days. Range is (-1,000,000,000 < days < 1,000,000,000)
Return Value
An OracleTimeStamp.
Exceptions
ArgumentOutofRangeException - The argument value is out of the specified
range.
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
AddHours
This method adds the supplied number of hours to the current instance.
Declaration
// C#
public OracleTimeStamp AddHours(double hours);
Parameters
■ hours
The supplied number of hours. Range is (-24,000,000,000 < hours <
24,000,000,000).
Return Value
An OracleTimeStamp.
Exceptions
ArgumentOutofRangeException - The argument value is out of the specified
range.
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
AddMilliseconds
This method adds the supplied number of milliseconds to the current instance.
Declaration
// C#
public OracleTimeStamp AddMilliseconds(double milliseconds);
Parameters
■ milliseconds
The supplied number of milliseconds. Range is (-8.64 * 1016< milliseconds <
8.64 * 1016).
Return Value
An OracleTimeStamp.
Exceptions
ArgumentOutofRangeException - The argument value is out of the specified
range.
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
AddMinutes
This method adds the supplied number of minutes to the current instance.
Declaration
// C#
public OracleTimeStamp AddMinutes(double minutes);
Parameters
■ minutes
The supplied number of minutes. Range is (-1,440,000,000,000 < minutes <
1,440,000,000,000).
Return Value
An OracleTimeStamp.
Exceptions
ArgumentOutofRangeException - The argument value is out of the specified
range.
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
AddMonths
This method adds the supplied number of months to the current instance.
Declaration
// C#
public OracleTimeStamp AddMonths(long months);
Parameters
■ months
The supplied number of months. Range is (-12,000,000,000 < months <
12,000,000,000).
Return Value
An OracleTimeStamp.
Exceptions
ArgumentOutofRangeException - The argument value is out of the specified
range.
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
AddNanoseconds
This method adds the supplied number of nanoseconds to the current instance.
Declaration
// C#
public OracleTimeStamp AddNanoseconds(long nanoseconds);
Parameters
■ nanoseconds
The supplied number of nanoseconds.
Return Value
An OracleTimeStamp.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
AddSeconds
This method adds the supplied number of seconds to the current instance.
Declaration
// C#
public OracleTimeStamp AddSeconds(double seconds);
Parameters
■ seconds
The supplied number of seconds. Range is (-8.64 * 1013< seconds < 8.64 * 1013).
Return Value
An OracleTimeStamp.
Exceptions
ArgumentOutofRangeException - The argument value is out of the specified
range.
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
AddYears
This method adds the supplied number of years to the current instance.
Declaration
// C#
public OracleTimeStamp AddYears(int years);
Parameters
■ years
The supplied number of years. Range is (-999,999,999 <= years < = 999,999,999)
Return Value
An OracleTimeStamp.
Exceptions
ArgumentOutofRangeException - The argument value is out of the specified
range.
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
CompareTo
This method compares the current OracleTimeStamp 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 to the current OracleTimeStamp instance.
Return Value
The method returns a number that is:
Less than zero: if the current OracleTimeStamp instance value is less than that of
obj.
Zero: if the current OracleTimeStamp instance and obj values are equal.
Greater than zero: if the current OracleTimeStamp instance value is greater than that
of obj.
Implements
IComparable
Exceptions
ArgumentException - The obj parameter is not of type OracleTimeStamp.
Remarks
The following rules apply to the behavior of this method.
■ The comparison must be between OracleTimeStamps. For example, comparing
an OracleTimeStamp instance with an OracleBinary instance is not allowed.
When an OracleTimeStamp is compared with a different type, an
ArgumentException is thrown.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
Equals
Overrides Object
This method determines whether or not an object has the same date and time as the
current OracleTimeStamp instance.
Declaration
// C#
public override bool Equals(object obj);
Parameters
■ obj
The object being compared to the current OracleTimeStamp instance.
Return Value
Returns true if the obj is of type OracleTimeStamp and represents the same date
and time; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStamp that has a value is greater than an OracleTimeStamp
that has a null value.
■ Two OracleTimeStamps that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
GetHashCode
Overrides Object
This method returns a hash code for the OracleTimeStamp instance.
Declaration
// C#
public override int GetHashCode();
Return Value
A number that represents the hash code.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
GetDaysBetween
This method subtracts an OracleTimeStamp value from the current instance and
returns an OracleIntervalDS that represents the time difference between the
supplied OracleTimeStamp structure and the current instance.
Declaration
// C#
public OracleIntervalDS GetDaysBetween(OracleTimeStamp value1);
Parameters
■ value1
The OracleTimeStamp value being subtracted.
Return Value
An OracleIntervalDS that represents the interval between two
OracleTimeStamp values.
Remarks
If either the current instance or the parameter has a null value, the returned
OracleIntervalDS has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
GetYearsBetween
This method subtracts an OracleTimeStamp value from the current instance and
returns an OracleIntervalYM that represents the time difference between the
OracleTimeStamp value and the current instance.
Declaration
// C#
public OracleIntervalYM GetYearsBetween(OracleTimeStamp value1);
Parameters
■ value1
The OracleTimeStamp value being subtracted.
Return Value
An OracleIntervalYM that represents the interval between two
OracleTimeStamp values.
Remarks
If either the current instance or the parameter has a null value, the returned
OracleIntervalYM has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
ToOracleDate
This method converts the current OracleTimeStamp structure to an OracleDate
structure.
Declaration
// C#
public OracleDate ToOracleDate();
Return Value
The returned OracleDate contains the date and time in the current instance.
Remarks
The precision of the OracleTimeStamp value can be lost during the conversion.
If the value of the OracleTimeStamp has a null value, the value of the returned
OracleDate structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
ToOracleTimeStampLTZ
This method converts the current OracleTimeStamp structure to an
OracleTimeStampLTZ structure.
Declaration
// C#
public OracleTimeStampLTZ ToOracleTimeStampLTZ();
Return Value
The returned OracleTimeStampLTZ contains date and time in the current instance.
Remarks
If the value of the current instance has a null value, the value of the returned
OracleTimeStampLTZ structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
ToOracleTimeStampTZ
This method converts the current OracleTimeStamp structure to an
OracleTimeStampTZ structure.
Declaration
// C#
public OracleTimeStampTZ ToOracleTimeStampTZ();
Return Value
The returned OracleTimeStampTZ contains the date and time from the
OracleTimeStamp and the time zone from the OracleGlobalization.TimeZone
of the thread.
Remarks
If the value of the current instance has a null value, the value of the returned
OracleTimeStampTZ structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
ToString
Overrides Object
This method converts the current OracleTimeStamp structure to a string.
Declaration
// C#
public override string ToString();
Return Value
A string that represents the same date and time as the current OracleTimeStamp
structure.
Remarks
The returned value is a string representation of an OracleTimeStamp in the format
specified by the OracleGlobalization.TimeStampFormat property of the thread.
The names and abbreviations used for months and days are in the language specified
by the OracleGlobalization's DateLanguage and Calendar properties of the
thread. 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 ToStringSample
{
static void Main()
{
// Set the nls_timestamp_format for the OracleTimeStamp(string)
// constructor
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampFormat = "DD-MON-YYYY HH:MI:SS.FF AM";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStamp Structure
■ OracleTimeStamp Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
OracleTimeStampLTZ Structure
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleTimeStampLTZ
Declaration
// ADO.NET 2.0: C#
public struct OracleTimeStampLTZ : IComparable, INullable, IXmlSerializable
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 OracleTimeStampLTZSample
{
static void Main()
{
// Illustrates usage of OracleTimeStampLTZ
// Display Local Time Zone Name
Console.WriteLine("Local Time Zone Name = " +
OracleTimeStampLTZ.GetLocalTimeZoneName());
OracleTimeStampLTZ tsLocal1 = OracleTimeStampLTZ.GetSysDate();
OracleTimeStampLTZ tsLocal2 = DateTime.Now;
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Members
■ OracleTimeStampLTZ Constructors
■ OracleTimeStampLTZ Static Fields
■ OracleTimeStampLTZ Static Methods
■ OracleTimeStampLTZ Static Operators
■ OracleTimeStampLTZ Static Type Conversions
■ OracleTimeStampLTZ Properties
■ OracleTimeStampLTZ Methods
OracleTimeStampLTZ Members
OracleTimeStampLTZ Constructors
OracleTimeStampLTZ constructors are listed in Table 14–100
OracleTimeStampLTZ Properties
The OracleTimeStampLTZ properties are listed in Table 14–105.
OracleTimeStampLTZ Methods
The OracleTimeStampLTZ methods are listed in Table 14–106.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
OracleTimeStampLTZ Constructors
Overload List:
■ OracleTimeStampLTZ(DateTime)
This constructor creates a new instance of the OracleTimeStampLTZ structure
and sets its value for date and time using the supplied DateTime value.
■ OracleTimeStampLTZ(string)
This constructor creates a new instance of the OracleTimeStampLTZ structure
and sets its value for date and time using the supplied string.
■ OracleTimeStampLTZ(int, int, int)
This constructor creates a new instance of the OracleTimeStampLTZ structure
and sets its value for date using year, month, and day.
■ OracleTimeStampLTZ(int, int, int, int, int, int)
This constructor creates a new instance of the OracleTimeStampLTZ structure
and sets its value for date and time using year, month, day, hour, minute, and
second.
■ OracleTimeStampLTZ(int, int, int, int, int, int, double)
This constructor creates a new instance of the OracleTimeStampLTZ structure
and sets its value for date and time using year, month, day, hour, minute, second,
and millisecond.
■ OracleTimeStampLTZ(int, int, int, int, int, int, int)
This constructor creates a new instance of the OracleTimeStampLTZ structure
and sets its value for date and time using year, month, day, hour, minute, second,
and nanosecond.
■ OracleTimeStampLTZ(byte [ ])
This constructor creates a new instance of the OracleTimeStampLTZ structure
and sets its value to the provided byte array, which is in the internal Oracle
TIMESTAMP WITH LOCAL TIME ZONE format.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
OracleTimeStampLTZ(DateTime)
This constructor creates a new instance of the OracleTimeStampLTZ structure and
sets its value for date and time using the supplied DateTime value.
Declaration
// C#
public OracleTimeStampLTZ (DateTime dt);
Parameters
■ dt
The supplied DateTime value.
Exceptions
ArgumentException - The dt parameter cannot be used to construct a valid
OracleTimeStampLTZ.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
OracleTimeStampLTZ(string)
This constructor creates a new instance of the OracleTimeStampLTZ structure and
sets its value for date and time using the supplied string.
Declaration
// C#
public OracleTimeStampLTZ(string tsStr);
Parameters
■ tsStr
A string that represents an Oracle TIMESTAMP WITH LOCAL TIME ZONE.
Exceptions
ArgumentException - The tsStr is an invalid string representation of an Oracle
TIMESTAMP WITH LOCAL TIME ZONE or the supplied tsStr is not in the timestamp
format specified by the OracleGlobalization.TimeStampFormat property of the
thread, which represents the Oracle NLS_TIMESTAMP_FORMAT parameter.
ArgumentNullException - The tsStr value 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.Client;
using Oracle.DataAccess.Types;
class OracleTimeStampLTZSample
{
static void Main()
{
// Set the nls_timestamp_format for the OracleTimeStampLTZ(string)
// constructor
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
■ Oracle Database SQL Reference for further information on date
format elements
Declaration
// C#
public OracleTimeStampLTZ(int year, int month, int day);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. 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 OracleTimeStampLTZ (that is, the day is out of range for the
month).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public OracleTimeStampLTZ (int year, int month, int day, int hour,
int minute, int second);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. 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 OracleTimeStampLTZ (that is, the day is out of range for the
month).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public OracleTimeStampLTZ(int year, int month, int day, int hour, int minute, int
second, double millisecond);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ milliSeconds
The milliseconds provided. Range of millisecond is (0 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 OracleTimeStampLTZ (that is, the day is out of range for the
month).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public OracleTimeStampLTZ (int year, int month, int day, int hour,
int minute, int second, int nanosecond);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ nanosecond
The nanosecond provided. Range of nanosecond is (0 to 999999999).
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 OracleTimeStampLTZ (that is, the day is out of range for the
month).
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
OracleTimeStampLTZ(byte [ ])
This constructor creates a new instance of the OracleTimeStampLTZ structure and
sets its value to the provided byte array, which is in the internal Oracle TIMESTAMP
WITH LOCAL TIME ZONE format.
Declaration
// C#
public OracleTimeStampLTZ (byte[] bytes);
Parameters
■ bytes
A byte array that represents an Oracle TIMESTAMP WITH LOCAL TIME ZONE in
Oracle internal format.
Exceptions
ArgumentException - bytes is not in an internal Oracle TIMESTAMP WITH LOCAL
TIME ZONE format or bytes is not a valid Oracle TIMESTAMP WITH LOCAL TIME
ZONE.
ArgumentNullException - bytes is null.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
MaxValue
This static field represents the maximum valid date for an OracleTimeStampLTZ
structure, which is December 31, 9999 23:59:59.999999999.
Declaration
// C#
public static readonly OracleTimeStampLTZ MaxValue;
Remarks
This value is the maximum date and time in the client time zone.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
MinValue
This static field represents the minimum valid date for an OracleTimeStampLTZ
structure, which is January 1, -4712 0:0:0.
Declaration
// C#
public static readonly OracleTimeStampLTZ MinValue;
Remarks
This value is the minimum date and time in the client time zone.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Null
This static field represents a null value that can be assigned to an instance of the
OracleTimeStampLTZ structure.
Declaration
// C#
public static readonly OracleTimeStampLTZ Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Equals
This static method determines if two OracleTimeStampLTZ values are equal.
Declaration
// C#
public static bool Equals(OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if two OracleTimeStampLTZ values are equal. Returns false
otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
GetLocalTimeZoneName
This static method gets the client's local time zone name.
Declaration
// C#
public static string GetLocalTimeZoneName();
Return Value
A string containing the local time zone.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
GetLocalTimeZoneOffset
This static method gets the client's local time zone offset relative to Coordinated
Universal Time (UTC).
Declaration
// C#
public static TimeSpan GetLocalTimeZoneOffset( );
Return Value
A TimeSpan structure containing the local time zone hours and time zone minutes.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
GetSysDate
This static method gets an OracleTimeStampLTZ structure that represents the
current date and time.
Declaration
// C#
public static OracleTimeStampLTZ GetSysDate();
Return Value
An OracleTimeStampLTZ structure that represents the current date and time.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
GreaterThan
This static method determines if the first of two OracleTimeStampLTZ values is
greater than the second.
Declaration
// C#
public static bool GreaterThan(OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if the first of two OracleTimeStampLTZ values is greater than the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
GreaterThanOrEqual
This static method determines if the first of two OracleTimeStampLTZ values is
greater than or equal to the second.
Declaration
// C#
public static bool GreaterThanOrEqual(OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if the first of two OracleTimeStampLTZ values is greater than or equal
to the second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
LessThan
This static method determines if the first of two OracleTimeStampLTZ values is less
than the second.
Declaration
// C#
public static bool LessThan(OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if the first of two OracleTimeStampLTZ values is less than the second.
Returns false otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
LessThanOrEqual
This static method determines if the first of two OracleTimeStampLTZ values is less
than or equal to the second.
Declaration
// C#
public static bool LessThanOrEqual(OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if the first of two OracleTimeStampLTZ values is less than or equal to
the second. Returns false otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
NotEquals
This static method determines if two OracleTimeStampLTZ values are not equal.
Declaration
// C#
public static bool NotEquals(OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if two OracleTimeStampLTZ values are not equal. Returns false
otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Parse
This static method creates an OracleTimeStampLTZ structure and sets its value
using the supplied string.
Declaration
// C#
public static OracleTimeStampLTZ Parse(string tsStr);
Parameters
■ tsStr
A string that represents an Oracle TIMESTAMP WITH LOCAL TIME ZONE.
Return Value
An OracleTimeStampLTZ structure.
Exceptions
ArgumentException - The tsStr parameter is an invalid string representation of an
Oracle TIMESTAMP WITH LOCAL TIME ZONE or the tsStr is not in the timestamp
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()
{
// Set the nls_timestamp_format for the Parse() method
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampFormat = "DD-MON-YYYY HH:MI:SS.FF AM";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
SetPrecision
This static method returns a new instance of an OracleTimeStampLTZ with the
specified fractional second precision.
Declaration
// C#
public static OracleTimeStampLTZ SetPrecision(OracleTimeStampLTZ value1,
int fracSecPrecision);
Parameters
■ value1
The provided OracleTimeStampLTZ object.
■ fracSecPrecision
The fractional second precision provided. Range of fractional second precision is
(0 to 9).
Return Value
An OracleTimeStampLTZ structure with the specified fractional second precision
Exceptions
ArgumentOutOfRangeException - fracSecPrecision is out of the specified
range.
Remarks
The value specified in the supplied fracSecPrecision parameter is used to
perform a rounding off operation on the supplied OracleTimeStampLTZ value.
Depending on this value, 0 or more trailing zeros are displayed in the string returned
by ToString().
Example
The OracleTimeStampLTZ with a value of "December 31, 9999 23:59:59.99"
results in the string "December 31, 9999 23:59:59.99000" when
SetPrecision() is called with the fractional second precision set to 5.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
operator+
operator+ adds the supplied value to the supplied OracleTimeStampLTZ and
returns a new OracleTimeStampLTZ structure.
Overload List:
■ operator + (OracleTimeStampLTZ, OracleIntervalDS)
This static operator adds the supplied OracleIntervalDS to the supplied
OracleTimeStampLTZ and returns a new OracleTimeStampLTZ structure.
■ operator + (OracleTimeStampLTZ, OracleIntervalYM)
This static operator adds the supplied OracleIntervalYM to the supplied
OracleTimeStampLTZ and returns a new OracleTimeStampLTZ structure.
■ operator + (OracleTimeStampLTZ, TimeSpan)
This static operator adds the supplied TimeSpan to the supplied
OracleTimeStampLTZ and returns a new OracleTimeStampLTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static operator +(OracleTimeStampLTZ value1,
OracleIntervalDS value2);
Parameters
■ value1
An OracleTimeStampLTZ.
■ value2
An OracleIntervalDS.
Return Value
An OracleTimeStampLTZ.
Remarks
If either parameter has a null value, the returned OracleTimeStampLTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static operator +(OracleTimeStampLTZ value1,
OracleIntervalYM value2);
Parameters
■ value1
An OracleTimeStampLTZ.
■ value2
An OracleIntervalYM.
Return Value
An OracleTimeStampLTZ.
Remarks
If either parameter has a null value, the returned OracleTimeStampLTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static operator +(OracleTimeStampLTZ value1, TimeSpan value2);
Parameters
■ value1
An OracleTimeStampLTZ.
■ value2
A TimeSpan.
Return Value
An OracleTimeStampLTZ.
Remarks
If the OracleTimeStampLTZ instance has a null value, the returned
OracleTimeStampLTZ has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
operator ==
This static operator determines if two OracleTimeStampLTZ values are equal.
Declaration
// C#
public static bool operator == (OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if they are the same; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
operator >
This static operator determines if the first of two OracleTimeStampLTZ values is
greater than the second.
Declaration
// C#
public static bool operator > (OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if the first OracleTimeStampLTZ value is greater than the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
operator >=
This static operator determines if the first of two OracleTimeStampLTZ values is
greater than or equal to the second.
Declaration
// C#
public static bool operator >= (OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
An OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if the first OracleTimeStampLTZ is greater than or equal to the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
operator !=
This static operator determines if two OracleTimeStampLTZ values are not equal.
Declaration
// C#
public static bool operator != (OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if two OracleTimeStampLTZ values are not equal; otherwise returns
false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
operator <
This static operator determines if the first of two OracleTimeStampLTZ values is less
than the second.
Declaration
// C#
public static bool operator < (OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if the first OracleTimeStampLTZ is less than the second; otherwise,
returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
operator <=
This static operator determines if the first of two OracleTimeStampLTZ values is less
than or equal to the second.
Declaration
// C#
public static bool operator <= (OracleTimeStampLTZ value1,
OracleTimeStampLTZ value2);
Parameters
■ value1
The first OracleTimeStampLTZ.
■ value2
The second OracleTimeStampLTZ.
Return Value
Returns true if the first OracleTimeStampLTZ is less than or equal to the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
operator -
operator- subtracts the supplied value, from the supplied OracleTimeStampLTZ
value, and returns a new OracleTimeStampLTZ structure.
Overload List:
■ operator - (OracleTimeStampLTZ, OracleIntervalDS)
This static operator subtracts the supplied OracleIntervalDS value, from the
supplied OracleTimeStampLTZ value, and return a new
OracleTimeStampLTZ structure.
■ operator - (OracleTimeStampLTZ, OracleIntervalYM)
This static operator subtracts the supplied OracleIntervalYM value, from the
supplied OracleTimeStampLTZ value, and returns a new
OracleTimeStampLTZ structure.
■ operator - (OracleTimeStampLTZ, TimeSpan)
This static operator subtracts the supplied TimeSpan value, from the supplied
OracleTimeStampLTZ value, and returns a new OracleTimeStampLTZ
structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static operator - (OracleTimeStampLTZ value1,
OracleIntervalDS value2);
Parameters
■ value1
An OracleTimeStampLTZ.
■ value2
An OracleIntervalDS instance.
Return Value
An OracleTimeStampLTZ structure.
Remarks
If either parameter has a null value, the returned OracleTimeStampLTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
Parameters
■ value1
An OracleTimeStampLTZ.
■ value2
An OracleIntervalYM.
Return Value
An OracleTimeStampLTZ structure.
Remarks
If either parameter has a null value, the returned OracleTimeStampLTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static operator -(OracleTimeStampLTZ value1, TimeSpan value2);
Parameters
■ value1
An OracleTimeStampLTZ.
■ value2
A TimeSpan.
Return Value
An OracleTimeStampLTZ structure.
Remarks
If the OracleTimeStampLTZ instance has a null value, the returned
OracleTimeStampLTZ structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Overload List:
■ explicit operator OracleTimeStampLTZ(OracleTimeStamp)
This static type conversion operator converts an OracleTimeStamp value to an
OracleTimeStampLTZ structure.
■ explicit operator OracleTimeStampLTZ(OracleTimeStampTZ)
This static type conversion operator converts an OracleTimeStampTZ value to
an OracleTimeStampLTZ structure.
■ explicit operator OracleTimeStampLTZ(string)
This static type conversion operator converts the supplied string to an
OracleTimeStampLTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static explicit operator OracleTimeStampLTZ (OracleTimeStamp value1);
Parameters
■ value1
An OracleTimeStamp.
Return Value
The OracleTimeStampLTZ structure contains the date and time of the
OracleTimeStampTZ structure.
Remarks
If the OracleTimeStamp structure has a null value, the returned
OracleTimeStampLTZ structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static explicit operator OracleTimeStampLTZ
(OracleTimeStampTZ value1);
Parameters
■ value1
An OracleTimeStampTZ instance.
Return Value
The OracleTimeStampLTZ structure contains the date and time in the
OracleTimeStampTZ structure (which is normalized to the client local time zone).
Remarks
If the OracleTimeStampTZ structure has a null value, the returned
OracleTimeStampLTZ structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static explicit operator OracleTimeStampLTZ (string tsStr);
Parameters
■ tsStr
A string representation of an Oracle TIMESTAMP WITH LOCAL TIME ZONE.
Return Value
A OracleTimeStampLTZ.
Exceptions
ArgumentException - ThetsStr parameter is an invalid string representation of an
Oracle TIMESTAMP WITH LOCAL TIME ZONE or the tsStr is not in the timestamp
format specified by the thread's OracleGlobalization.TimeStampFormat
property, which represents the Oracle NLS_TIMESTAMP_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.Types;
using Oracle.DataAccess.Client;
class OracleTimeStampLTZSample
{
static void Main()
{
// Set the nls_timestamp_format for the OracleTimeStampLTZ(string)
// constructor
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampFormat = "DD-MON-YYYY HH:MI:SS.FF AM";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
■ Oracle Database SQL Reference for further information on
datetime format elements
Overload List:
■ implicit operator OracleTimeStampLTZ(OracleDate)
This static type conversion operator converts an OracleDate value to an
OracleTimeStampLTZ structure.
■ implicit operator OracleTimeStampLTZ(DateTime)
This static type conversion operator converts a DateTime structure to an
OracleTimeStampLTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static implicit operator OracleTimeStampLTZ(OracleDate value1);
Parameters
■ value1
An OracleDate.
Return Value
The returned OracleTimeStampLTZ structure contains the date and time in the
OracleDate structure.
Remarks
If the OracleDate structure has a null value, the returned OracleTimeStampLTZ
structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static implicit operator OracleTimeStampLTZ(DateTime value1);
Parameters
■ value1
A DateTime structure.
Return Value
An OracleTimeStampLTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Declaration
// C#
public static explicit operator DateTime(OracleTimeStampLTZ value1);
Parameters
■ value1
An OracleTimeStampLTZ instance.
Return Value
A DateTime that contains the date and time in the current instance.
Exceptions
OracleNullValueException - The OracleTimeStampLTZ structure has a null
value.
Remarks
The precision of the OracleTimeStampLTZ value can be lost during the conversion.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
OracleTimeStampLTZ Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
BinData
This property returns an array of bytes that represents an Oracle TIMESTAMP WITH
LOCAL TIME ZONE in Oracle internal format.
Declaration
// C#
public byte[] BinData {get;}
Property Value
A byte array that represents an Oracle TIMESTAMP WITH LOCAL TIME ZONE internal
format.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Day
This property specifies the day component of an OracleTimeStampLTZ.
Declaration
// C#
public int Day{get;}
Property Value
A number that represents the day. Range of Day is (1 to 31).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
IsNull
This property indicates whether or not the current instance has a null value.
Declaration
// C#
public bool IsNull{get;}
Property Value
Returns true if the current instance contains a null value; otherwise, returns false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Hour
This property specifies the hour component of an OracleTimeStampLTZ.
Declaration
// C#
public int Hour{get;}
Property Value
A number that represents the hour. Range of Hour is (0 to 23).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Millisecond
This property gets the millisecond component of an OracleTimeStampLTZ.
Declaration
// C#
public double Millisecond{get;}
Property Value
A number that represents a millisecond. Range of Millisecond is (0 to 999.999999)
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Minute
This property gets the minute component of an OracleTimeStampLTZ.
Declaration
// C#
public int Minute{get;}
Property Value
A number that represent a minute. Range of Minute is (0 to 59).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Month
This property gets the month component of an OracleTimeStampLTZ.
Declaration
// C#
public int Month{get;}
Property Value
A number that represents a month. Range of Month is (1 to 12).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Nanosecond
This property gets the nanosecond component of an OracleTimeStampLTZ.
Declaration
// C#
public int Nanosecond{get;}
Property Value
A number that represents a nanosecond. Range of Nanosecond is (0 to 999999999).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Second
This property gets the second component of an OracleTimeStampLTZ.
Declaration
// C#
public int Second{get;}
Property Value
A number that represents a second. Range of Second is (0 to 59).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Value
This property specifies the date and time that is stored in the OracleTimeStampLTZ
structure.
Declaration
// C#
public DateTime Value{get;}
Property Value
A DateTime.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Year
This property gets the year component of an OracleTimeStampLTZ.
Declaration
// C#
public int Year{get;}
Property Value
A number that represents a year. The range of Year is (-4712 to 9999).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
OracleTimeStampLTZ Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
AddDays
This method adds the supplied number of days to the current instance.
Declaration
// C#
public OracleTimeStampLTZ AddDays(double days);
Parameters
■ days
The supplied number of days. Range is (-1,000,000,000 < days < 1,000,000,000)
Return Value
An OracleTimeStampLTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
AddHours
This method adds the supplied number of hours to the current instance.
Declaration
// C#
public OracleTimeStampLTZ AddHours(double hours);
Parameters
■ hours
The supplied number of hours. Range is (-24,000,000,000 < hours <
24,000,000,000).
Return Value
An OracleTimeStampLTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
AddMilliseconds
This method adds the supplied number of milliseconds to the current instance.
Declaration
// C#
public OracleTimeStampLTZ AddMilliseconds(double milliseconds);
Parameters
■ milliseconds
The supplied number of milliseconds. Range is (-8.64 * 1016< milliseconds <
8.64 * 1016).
Return Value
An OracleTimeStampLTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
AddMinutes
This method adds the supplied number of minutes to the current instance.
Declaration
// C#
public OracleTimeStampLTZ AddMinutes(double minutes);
Parameters
■ minutes
The supplied number of minutes. Range is (-1,440,000,000,000 < minutes <
1,440,000,000,000).
Return Value
An OracleTimeStampLTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
AddMonths
This method adds the supplied number of months to the current instance.
Declaration
// C#
public OracleTimeStampLTZ AddMonths(long months);
Parameters
■ months
The supplied number of months. Range is (-12,000,000,000 < months <
12,000,000,000).
Return Value
An OracleTimeStampLTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
AddNanoseconds
This method adds the supplied number of nanoseconds to the current instance.
Declaration
// C#
public OracleTimeStampLTZ AddNanoseconds(long nanoseconds);
Parameters
■ nanoseconds
The supplied number of nanoseconds.
Return Value
An OracleTimeStampLTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
AddSeconds
This method adds the supplied number of seconds to the current instance.
Declaration
// C#
public OracleTimeStampLTZ AddSeconds(double seconds);
Parameters
■ seconds
The supplied number of seconds. Range is (-8.64 * 1013< seconds < 8.64 * 1013).
Return Value
An OracleTimeStampLTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
AddYears
This method adds the supplied number of years to the current instance
Declaration
// C#
public OracleTimeStampLTZ AddYears(int years);
Parameters
■ years
The supplied number of years. Range is (-999,999,999 <= years < = 999,999,999)
Return Value
An OracleTimeStampLTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
CompareTo
This method compares the current OracleTimeStampLTZ 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 to the current OracleTimeStampLTZ instance.
Return Value
The method returns a number that is:
■ Less than zero: if the current OracleTimeStampLTZ instance value is less than
that of obj.
■ Zero: if the current OracleTimeStampLTZ instance and obj values are equal.
■ Greater than zero: if the current OracleTimeStampLTZ instance value is greater
than that of obj.
Implements
IComparable
Exceptions
ArgumentException - The obj parameter is not of type OracleTimeStampLTZ.
Remarks
The following rules apply to the behavior of this method.
■ The comparison must be between OracleTimeStampLTZs. For example,
comparing an OracleTimeStampLTZ instance with an OracleBinary instance
is not allowed. When an OracleTimeStampLTZ is compared with a different
type, an ArgumentException is thrown.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
Equals
Overrides Object
This method determines whether or not an object has the same date and time as the
current OracleTimeStampLTZ instance.
Declaration
// C#
public override bool Equals(object obj);
Parameters
■ obj
The object being compared to the current OracleTimeStampLTZ instance.
Return Value
Returns true if the obj is of type OracleTimeStampLTZ and represents the same
date and time; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampLTZ that has a value is greater than an
OracleTimeStampLTZ that has a null value.
■ Two OracleTimeStampLTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
GetHashCode
Overrides Object
This method returns a hash code for the OracleTimeStampLTZ instance.
Declaration
// C#
public override int GetHashCode();
Return Value
A number that represents the hash code.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
GetDaysBetween
This method subtracts an OracleTimeStampLTZ value from the current instance and
returns an OracleIntervalDS that represents the difference.
Declaration
// C#
public OracleIntervalDS GetDaysBetween(OracleTimeStampLTZ value1);
Parameters
■ value1
The OracleTimeStampLTZ value being subtracted.
Return Value
An OracleIntervalDS that represents the interval between two
OracleTimeStampLTZ values.
Remarks
If either the current instance or the parameter has a null value, the returned
OracleIntervalDS has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
GetYearsBetween
This method subtracts an OracleTimeStampLTZ value from the current instance and
returns an OracleIntervalYM that represents the time interval.
Declaration
// C#
public OracleIntervalYM GetYearsBetween(OracleTimeStampLTZ value1);
Parameters
■ value1
The OracleTimeStampLTZ value being subtracted.
Return Value
An OracleIntervalYM that represents the interval between two
OracleTimeStampLTZ values.
Remarks
If either the current instance or the parameter has a null value, the returned
OracleIntervalYM has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
ToOracleDate
This method converts the current OracleTimeStampLTZ structure to an
OracleDate structure.
Declaration
// C#
public OracleDate ToOracleDate();
Return Value
The returned OracleDate structure contains the date and time in the current
instance.
Remarks
The precision of the OracleTimeStampLTZ value can be lost during the conversion.
If the current instance has a null value, the value of the returned OracleDate
structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
ToOracleTimeStamp
This method converts the current OracleTimeStampLTZ structure to an
OracleTimeStamp structure.
Declaration
// C#
public OracleTimeStamp ToOracleTimeStamp();
Return Value
The returned OracleTimeStamp contains the date and time in the current instance.
Remarks
If the current instance has a null value, the value of the returned OracleTimeStamp
structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
ToOracleTimeStampTZ
This method converts the current OracleTimeStampLTZ structure to an
OracleTimeStampTZ structure.
Declaration
// C#
public OracleTimeStampTZ ToOracleTimeStampTZ();
Return Value
The returned OracleTimeStampTZ contains the date and time of the current
instance, with the time zone set to the OracleGlobalization.TimeZone from the
thread.
Remarks
If the current instance has a null value, the value of the returned
OracleTimeStampTZ structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
ToString
Overrides Object
This method converts the current OracleTimeStampLTZ structure to a string.
Declaration
// C#
public override string ToString();
Return Value
A string that represents the same date and time as the current
OracleTimeStampLTZ structure.
Remarks
The returned value is a string representation of the OracleTimeStampLTZ in the
format specified by the OracleGlobalization.TimeStampFormat property of the
thread.
The names and abbreviations used for months and days are in the language specified
by the DateLanguage and Calendar properties of the thread's
Example
// C#
using System;
using Oracle.DataAccess.Types;
using Oracle.DataAccess.Client;
class ToStringSample
{
static void Main()
{
// Set the nls_timestamp_format for the OracleTimeStampLTZ(string)
// constructor
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampFormat = "DD-MON-YYYY HH:MI:SS.FF AM";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
ToUniversalTime
This method converts the current local time to Coordinated Universal Time (UTC).
Declaration
// C#
public OracleTimeStampTZ ToUniversalTime();
Return Value
An OracleTimeStampTZ structure.
Remarks
If the current instance has a null value, the value of the returned
OracleTimeStampTZ structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampLTZ Structure
■ OracleTimeStampLTZ Members
OracleTimeStampTZ Structure
Class Inheritance
System.Object
System.ValueType
Oracle.DataAccess.Types.OracleTimeStampTZ
Declaration
// ADO.NET 2.0: C#
public struct OracleTimeStampTZ : IComparable, INullable, IXmlSerializable
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 OracleTimeStampTZSample
{
static void Main()
{
// Set the nls parameters for the current thread
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeZone = "US/Eastern";
info.TimeStampFormat = "DD-MON-YYYY HH:MI:SS.FF AM";
info.TimeStampTZFormat = "DD-MON-YYYY HH:MI:SS.FF AM TZR";
OracleGlobalization.SetThreadInfo(info);
// Display information
Console.WriteLine("tstz1.TimeZone = " + tstz1.TimeZone);
// Prints "US/Pacific"
// Prints "US/Eastern"
Console.WriteLine("idsDiff.Hours = " + idsDiff.Hours); // Prints 3
Console.WriteLine("idsDiff.Minutes = " + idsDiff.Minutes); // Prints 0
}
}
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Members
■ OracleTimeStampTZ Constructors
■ OracleTimeStampTZ Static Fields
■ OracleTimeStampTZ Static Methods
■ OracleTimeStampTZ Static Operators
■ OracleTimeStampTZ Static Type Conversions
■ OracleTimeStampTZ Properties
■ OracleTimeStampTZ Methods
OracleTimeStampTZ Members
OracleTimeStampTZ Constructors
OracleTimeStampTZ constructors are listed in Table 14–113
OracleTimeStampTZ Properties
The OracleTimeStampTZ properties are listed in Table 14–118.
OracleTimeStampTZ Methods
The OracleTimeStampTZ methods are listed in Table 14–119.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
OracleTimeStampTZ Constructors
Overload List:
■ OracleTimeStampTZ(DateTime)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using the supplied DateTime value.
■ OracleTimeStampTZ(DateTime, string)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using the supplied DateTime value and the
supplied time zone data.
■ OracleTimeStampTZ(string)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using the supplied string.
■ OracleTimeStampTZ(int, int, int)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using year, month, and day.
■ OracleTimeStampTZ(int, int, int, string)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using year, month, day, and time zone data.
■ OracleTimeStampTZ(int, int, int, int, int, int)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using year, month, day, hour, minute, and second.
■ OracleTimeStampTZ(int, int, int, int, int, int, string)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using year, month, day, hour, minute, second, and
time zone data.
■ OracleTimeStampTZ(int, int, int, int, int, int, double)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using year, month, day, hour, minute, second, and
millisecond.
■ OracleTimeStampTZ(int, int, int, int, int, int, double, string)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using year, month, day, hour, minute, second,
millisecond, and time zone data.
■ OracleTimeStampTZ(int, int, int, int, int, int, int)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using year, month, day, hour, minute, second, and
nanosecond.
■ OracleTimeStampTZ(int, int, int, int, int, int, int, string)
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
OracleTimeStampTZ(DateTime)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using the supplied DateTime value.
Declaration
// C#
public OracleTimeStampTZ (DateTime dt);
Parameters
■ dt
The supplied DateTime value.
Remarks
The time zone is set to the OracleGlobalization.TimeZone of the thread.
Exceptions
ArgumentException - The dt parameter cannot be used to construct a valid
OracleTimeStampTZ.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
OracleTimeStampTZ(DateTime, string)
This constructor creates a new instance of the OracleTimeStampTZ structure with
the supplied DateTime value and the time zone data.
Declaration
// C#
public OracleTimeStampTZ (DateTime value1, string timeZone);
Parameters
■ value1
The supplied DateTime value.
■ timeZone
The time zone data provided.
Exceptions
ArgumentException - The argument values of the parameters cannot be used to
construct a valid OracleTimeStampTZ.
Remarks
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.
If time zone is null, the OracleGlobalization.TimeZone of the thread is used.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
OracleTimeStampTZ(string)
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value for date and time using the supplied string.
Declaration
// C#
public OracleTimeStampTZ (string tsStr);
Parameters
■ tsStr
A string that represents an Oracle TIMESTAMP WITH TIME ZONE.
Exceptions
ArgumentException - The tsStr is an invalid string representation of an Oracle
TIMESTAMP WITH TIME ZONE or the tsStr is not in the timestamp format specified
by the OracleGlobalization.TimeStampTZFormat property of the thread.
ArgumentNullException - The tsStr value 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.Client;
using Oracle.DataAccess.Types;
class OracleTimeStampTZSample
{
static void Main()
{
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampTZFormat = "DD-MON-YYYY HH:MI:SS.FF AM TZR";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
■ Oracle Database SQL Reference for further information on date
format elements
Declaration
// C#
public OracleTimeStampTZ(int year, int month, int day);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. 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 OracleTimeStampTZ (that is, the day is out of range for the month).
Remarks
The time zone is set to the OracleGlobalization.TimeZone of the thread.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public OracleTimeStampTZ(int year, int month, int day,
string timeZone);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ timeZone
The time zone data provided.
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 OracleTimeStampTZ (that is, the day is out of range for the month
or the time zone is invalid).
Remarks
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.
If time zone is null, the OracleGlobalization.TimeZone of the thread is used.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public OracleTimeStampTZ(int year, int month, int day, int hour,
int minute, int second);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. 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 OracleTimeStampTZ (that is, the day is out of range for the month).
Remarks
The time zone is set to the OracleGlobalization.TimeZone of the thread.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public OracleTimeStampTZ (int year, int month, int day, int hour,
int minute, int second, string timeZone);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ timeZone
The time zone data provided.
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 OracleTimeStampTZ (that is, the day is out of range of the month
or the time zone is invalid).
Remarks
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.
If time zone is null, the OracleGlobalization.TimeZone of the thread is used.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public OracleTimeStampTZ(int year, int month, int day, int hour,
int minute, int second, double millisecond);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ millisecond
The millisecond provided. Range of millisecond is (0 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 OracleTimeStampTZ (that is, the day is out of range for the month).
Remarks
The time zone is set to the OracleGlobalization.TimeZone of the thread.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public OracleTimeStampTZ(int year, int month, int day, int hour,
int minute, int second, double millisecond, string timeZone);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ millisecond
The millisecond provided. Range of millisecond is (0 to 999.999999).
■ timeZone
The time zone data provided.
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 OracleTimeStampTZ (that is, the day is out of range for the month
or the time zone is invalid).
Remarks
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public OracleTimeStampTZ(int year, int month, int day, int hour,
int minute, int second, int nanosecond);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ nanosecond
The nanosecond provided. Range of nanosecond is (0 to 999999999).
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 OracleTimeStampTZ (that is, the day is out of range for the month).
Remarks
The time zone is set to the OracleGlobalization.TimeZone of the thread.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public OracleTimeStampTZ(int year, int month, int day, int hour,
int minute, int second, int nanosecond, string timeZone);
Parameters
■ year
The year provided. Range of year is (-4712 to 9999).
■ month
The month provided. Range of month is (1 to 12).
■ day
The day provided. Range of day is (1 to 31).
■ hour
The hour provided. Range of hour is (0 to 23).
■ minute
The minute provided. Range of minute is (0 to 59).
■ second
The second provided. Range of second is (0 to 59).
■ nanosecond
The nanosecond provided. Range of nanosecond is (0 to 999999999).
■ timeZone
The time zone data provided.
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 OracleTimeStampTZ (that is, the day is out of range for the month
or the time zone is invalid).
Remarks
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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
OracleTimeStampTZ(byte [ ])
This constructor creates a new instance of the OracleTimeStampTZ structure and
sets its value to the provided byte array, that represents the internal Oracle
TIMESTAMP WITH TIME ZONE format.
Declaration
// C#
public OracleTimeStampLTZ (byte[] bytes);
Parameters
■ bytes
The provided byte array that represents an Oracle TIMESTAMP WITH TIME ZONE
in Oracle internal format.
Exceptions
ArgumentException - bytes is not in internal Oracle TIMESTAMP WITH TIME ZONE
format or bytes is not a valid Oracle TIMESTAMP WITH TIME ZONE.
ArgumentNullException - bytes is null.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
MaxValue
This static field represents the maximum valid datetime time for an
OracleTimeStampTZ structure in UTC, which is December 31,
999923:59:59.999999999.
Declaration
// C#
public static readonly OracleTimeStampTZ MaxValue;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
MinValue
This static field represents the minimum valid datetime for an OracleTimeStampTZ
structure in UTC, which is January 1, -4712 0:0:0.
Declaration
// C#
public static readonly OracleTimeStampTZ MinValue;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Null
This static field represents a null value that can be assigned to an instance of the
OracleTimeStampTZ structure.
Declaration
// C#
public static readonly OracleTimeStampTZ Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Equals
This static method determines if two OracleTimeStampTZ values are equal.
Declaration
// C#
public static bool Equals(OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if two OracleTimeStampTZ values are equal. Returns false
otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
GetSysDate
This static method gets an OracleTimeStampTZ structure that represents the current
date and time.
Declaration
// C#
public static OracleTimeStampTZ GetSysDate();
Return Value
An OracleTimeStampTZ structure that represents the current date and time.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
GreaterThan
This static method determines if the first of two OracleTimeStampTZ values is
greater than the second.
Declaration
// C#
public static bool GreaterThan(OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if the first of two OracleTimeStampTZ values is greater than the
second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
GreaterThanOrEqual
This static method determines if the first of two OracleTimeStampTZ values is
greater than or equal to the second.
Declaration
// C#
public static bool GreaterThanOrEqual(OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if the first of two OracleTimeStampTZ values is greater than or equal
to the second; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
LessThan
This static method determines if the first of two OracleTimeStampTZ values is less
than the second.
Declaration
// C#
public static bool LessThan(OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if the first of two OracleTimeStampTZ values is less than the second.
Returns false otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
LessThanOrEqual
This static method determines if the first of two OracleTimeStampTZ values is less
than or equal to the second.
Declaration
// C#
public static bool LessThanOrEqual(OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if the first of two OracleTimeStampTZ values is less than or equal to
the second. Returns false otherwise.
Remarks
The following rules apply to the behavior of this method.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
NotEquals
This static method determines if two OracleTimeStampTZ values are not equal.
Declaration
// C#
public static bool NotEquals(OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if two OracleTimeStampTZ values are not equal. Returns false
otherwise.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Parse
This static method returns an OracleTimeStampTZ structure and sets its value for
date and time using the supplied string.
Declaration
// C#
public static OracleTimeStampTZ Parse(string tsStr);
Parameters
■ tsStr
A string that represents an Oracle TIMESTAMP WITH TIME ZONE.
Return Value
An OracleTimeStampTZ structure.
Exceptions
ArgumentException - The tsStr is an invalid string representation of an Oracle
TIMESTAMP WITH TIME ZONE or the tsStr is not in the timestamp format specified
by the OracleGlobalization.TimeStampTZFormat property of the thread, which
represents the Oracle NLS_TIMESTAMP_TZ_FORMAT parameter.
ArgumentNullException - The tsStr value 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.Client;
using Oracle.DataAccess.Types;
class ParseSample
{
static void Main()
{
// Set the nls_timestamp_tz_format for the Parse() method
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampTZFormat = "DD-MON-YYYY HH:MI:SS.FF AM TZR";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
SetPrecision
This static method returns a new instance of an OracleTimeStampTZ with the
specified fractional second precision.
Declaration
// C#
public static OracleTimeStampTZ SetPrecision(OracleTimeStampTZ value1,
int fracSecPrecision);
Parameters
■ value1
The provided OracleTimeStampTZ object.
■ fracSecPrecision
The fractional second precision provided. Range of fractional second precision is
(0 to 9).
Return Value
An OracleTimeStampTZ structure with the specified fractional second precision
Exceptions
ArgumentOutOfRangeException - fracSecPrecision is out of the specified
range.
Remarks
The value specified in the supplied fracSecPrecision is used to perform a
rounding off operation on the supplied OracleTimeStampTZ value. Depending on
this value, 0 or more trailing zeros are displayed in the string returned by
ToString().
Example
The OracleTimeStampTZ with a value of "December 31, 9999 23:59:59.99
US/Pacific" results in the string "December 31, 9999 23:59:59.99000
US/Pacific" when SetPrecision() is called with the fractional second precision
set to 5.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
operator +
operator+ adds the supplied structure to the supplied OracleTimeStampTZ and
returns a new OracleTimeStampTZ structure.
Overload List:
■ operator +(OracleTimeStampTZ, OracleIntervalDS)
This static operator adds the supplied OracleIntervalDS to the supplied
OracleTimeStampTZ and returns a new OracleTimeStampTZ structure.
■ operator +(OracleTimeStampTZ, OracleIntervalYM)
This static operator adds the supplied OracleIntervalYM to the supplied
OracleTimeStampTZ and returns a new OracleTimeStampTZ structure.
■ operator +(OracleTimeStampTZ, TimeSpan)
This static operator adds the supplied TimeSpan to the supplied
OracleTimeStampTZ and returns a new OracleTimeStampTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public static operator +(OracleTimeStampTZ value1,
OracleIntervalDS value2);
Parameters
■ value1
An OracleTimeStampTZ.
■ value2
An OracleIntervalDS.
Return Value
An OracleTimeStampTZ.
Remarks
If either parameter has a null value, the returned OracleTimeStampTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public static operator +(OracleTimeStampTZ value1,
OracleIntervalYM value2);
Parameters
■ value1
An OracleTimeStampTZ.
■ value2
An OracleIntervalYM.
Return Value
An OracleTimeStampTZ.
Remarks
If either parameter has a null value, the returned OracleTimeStampTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public static operator +(OracleTimeStampTZ value1, TimeSpan value2);
Parameters
■ value1
An OracleTimeStampTZ.
■ value2
A TimeSpan.
Return Value
An OracleTimeStampTZ.
Remarks
If the OracleTimeStampTZ instance has a null value, the returned
OracleTimeStampTZ has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
operator ==
This static operator determines if two OracleTimeStampTZ values are equal.
Declaration
// C#
public static bool operator == (OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
Return Value
Returns true if they are equal; otherwise returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
operator >
This static operator determines if the first of two OracleTimeStampTZ values is
greater than the second.
Declaration
// C#
public static bool operator > (OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if the first OracleTimeStampTZ value is greater than the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
operator >=
This static operator determines if the first of two OracleTimeStampTZ values is
greater than or equal to the second.
Declaration
// C#
public static bool operator >= (OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if the first OracleTimeStampTZ is greater than or equal to the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
operator !=
This static operator determines if two OracleTimeStampTZ values are not equal.
Declaration
// C#
public static bool operator != (OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if two OracleTimeStampTZ values are not equal; otherwise, returns
false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
operator <
This static operator determines if the first of two OracleTimeStampTZ values is less
than the second.
Declaration
// C#
public static bool operator < (OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if the first OracleTimeStampTZ is less than the second; otherwise
returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
operator <=
This static operator determines if the first of two OracleTimeStampTZ values is less
than or equal to the second.
Declaration
// C#
public static bool operator <= (OracleTimeStampTZ value1,
OracleTimeStampTZ value2);
Parameters
■ value1
The first OracleTimeStampTZ.
■ value2
The second OracleTimeStampTZ.
Return Value
Returns true if the first OracleTimeStampTZ is less than or equal to the second;
otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
operator -
operator- subtracts the supplied value, from the supplied OracleTimeStampTZ
value, and returns a new OracleTimeStampTZ structure.
Overload List:
■ operator - (OracleTimeStampTZ, OracleIntervalDS)
This static operator subtracts the supplied OracleIntervalDS value, from the
supplied OracleTimeStampTZ value, and return a new OracleTimeStampTZ
structure.
■ operator - (OracleTimeStampTZ, OracleIntervalYM)
This static operator subtracts the supplied OracleIntervalYM value, from the
supplied OracleTimeStampTZ value, and returns a new OracleTimeStampTZ
structure.
■ operator - (OracleTimeStampTZ value1, TimeSpan value2)
This static operator subtracts the supplied TimeSpan value, from the supplied
OracleTimeStampTZ value, and returns a new OracleTimeStampTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public static operator - (OracleTimeStampTZ value1,
OracleIntervalDS value2);
Parameters
■ value1
An OracleTimeStampTZ.
■ value2
An OracleIntervalDS.
Return Value
An OracleTimeStampTZ structure.
Remarks
If either parameter has a null value, the returned OracleTimeStampTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public static operator - (OracleTimeStampTZ value1,
OracleIntervalYM value2);
Parameters
■ value1
An OracleTimeStampTZ.
■ value2
An OracleIntervalYM.
Return Value
An OracleTimeStampTZ structure.
Remarks
If either parameter has a null value, the returned OracleTimeStampTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Declaration
// C#
public static operator - (OracleTimeStampTZ value1, TimeSpan value2);
Parameters
■ value1
An OracleTimeStampTZ.
■ value2
A TimeSpan.
Return Value
An OracleTimeStampTZ structure.
Remarks
If the OracleTimeStampTZ instance has a null value, the returned
OracleTimeStampTZ structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Overload List:
■ explicit operator OracleTimeStampTZ(OracleTimeStamp)
This static type conversion operator converts an OracleTimeStamp value to an
OracleTimeStampTZ structure.
■ explicit operator OracleTimeStampTZ(OracleTimeStampLTZ)
This static type conversion operator converts an OracleTimeStampLTZ value to
an OracleTimeStampTZ structure.
■ explicit operator OracleTimeStampTZ(string)
This static type conversion operator converts the supplied string value to an
OracleTimeStampTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
Declaration
// C#
public static explicit operator OracleTimeStampTZ(OracleTimeStamp value1);
Parameters
■ value1
An OracleTimeStamp.
Return Value
The returned OracleTimeStampTZ contains the date and time from the
OracleTimeStamp and the time zone from the OracleGlobalization.TimeZone
of the thread.
Remarks
The OracleGlobalization.TimeZone of the thread is used to convert from an
OracleTimeStamp structure to an OracleTimeStampTZ structure.
If the OracleTimeStamp structure has a null value, the returned
OracleTimeStampTZ structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
Declaration
// C#
public static explicit operator OracleTimeStampTZ(OracleTimeStampLTZ value1);
Parameters
■ value1
An OracleTimeStampLTZ.
Return Value
The returned OracleTimeStampTZ contains the date and time from the
OracleTimeStampLTZ and the time zone from the
OracleGlobalization.TimeZone of the thread.
Remarks
If the OracleTimeStampLTZ structure has a null value, the returned
OracleTimeStampTZ structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
Declaration
// C#
public static explicit operator OracleTimeStampTZ(string tsStr);
Parameters
■ tsStr
A string representation of an Oracle TIMESTAMP WITH TIME ZONE.
Return Value
An OracleTimeStampTZ value.
Exceptions
ArgumentException - The tsStr is an invalid string representation of an Oracle
TIMESTAMP WITH TIME ZONE. or the tsStr is not in the timestamp format specified
by the thread's OracleGlobalization.TimeStampTZFormat property, which
represents the Oracle NLS_TIMESTAMP_TZ_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 OracleTimeStampTZSample
{
static void Main()
{
// Set the nls_timestamp_tz_format for the explicit operator
// OracleTimeStampTZ(string)
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeStampTZFormat = "DD-MON-YYYY HH:MI:SS.FF AM TZR";
OracleGlobalization.SetThreadInfo(info);
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
Overload List:
■ implicit operator OracleTimeStampTZ(OracleDate)
This static type conversion operator converts an OracleDate value to an
OracleTimeStampTZ structure.
■ implicit operator OracleTimeStampTZ(DateTime)
This static type conversion operator converts a DateTime structure to an
OracleTimeStampTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
Declaration
// C#
public static implicit operator OracleTimeStampTZ(OracleDate value1);
Parameters
■ value1
An OracleDate.
Return Value
The returned OracleTimeStampTZ contains the date and time from the
OracleDate and the time zone from the OracleGlobalization.TimeZone of the
thread.
Remarks
The OracleGlobalization.TimeZone of the thread is used to convert from an
OracleDate to an OracleTimeStampTZ structure. If the OracleDate structure has
a null value, the returned OracleTimeStampTZ structure also has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
Declaration
// C#
public static implicit operator OracleTimeStampTZ (DateTime value1);
Parameters
■ value1
A DateTime structure.
Return Value
The returned OracleTimeStampTZ contains the date and time from the DateTime
and the time zone from the OracleGlobalization.TimeZone of the thread.
Remarks
The OracleGlobalization.TimeZone of the thread is used to convert from a
DateTime to an Oracle TimeStampTZ structure.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
Declaration
// C#
public static explicit operator DateTime(OracleTimeStampTZ value1);
Parameters
■ value1
An OracleTimeStampTZ.
Return Value
A DateTime containing the date and time in the current instance, but with the time
zone information in the current instance truncated.
Exceptions
OracleNullValueException - The OracleTimeStampTZ structure has a null
value.
Remarks
The precision of the OracleTimeStampTZ value can be lost during the conversion,
and the time zone information in the current instance is truncated
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
OracleTimeStampTZ Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
BinData
This property returns an array of bytes that represents an Oracle TIMESTAMP WITH
TIME ZONE in Oracle internal format.
Declaration
// C#
public byte[] BinData {get;}
Property Value
The provided byte array that represents an Oracle TIMESTAMP WITH TIME ZONE in
Oracle internal format.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Day
This property specifies the day component of an OracleTimeStampTZ in the current
time zone.
Declaration
// C#
public int Day{get;}
Property Value
A number that represents the day. Range of Day is (1 to 31).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
IsNull
This property indicates whether or not 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.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Hour
This property specifies the hour component of an OracleTimeStampTZ in the
current time zone.
Declaration
// C#
public int Hour{get;}
Property Value
A number that represents the hour. Range of Hour is (0 to 23).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Millisecond
This property gets the millisecond component of an OracleTimeStampTZ in the
current time zone.
Declaration
// C#
public double Millisecond{get;}
Property Value
A number that represents a millisecond. Range of Millisecond is (0 to 999.999999)
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Minute
This property gets the minute component of an OracleTimeStampTZ in the current
time zone.
Declaration
// C#
public int Minute{get;}
Property Value
A number that represent a minute. Range of Minute is (0 to 59).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Month
This property gets the month component of an OracleTimeStampTZ in the current
time zone
Declaration
// C#
public int Month{get;}
Property Value
A number that represents a month. Range of Month is (1 to 12).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Nanosecond
This property gets the nanosecond component of an OracleTimeStampTZ in the
current time zone.
Declaration
// C#
public int Nanosecond{get;}
Property Value
A number that represents a nanosecond. Range of Nanosecond is (0 to 999999999).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Second
This property gets the second component of an OracleTimeStampTZ in the current
time zone.
Declaration
// C#
public int Second{get;}
Property Value
A number that represents a second. Range of Second is (0 to 59).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
TimeZone
This property returns the time zone of the OracleTimeStampTZ instance.
Declaration
// C#
public string TimeZone{get;}
Property Value
A string that represents the time zone.
Remarks
If no time zone is specified in the constructor, this property is set to the thread's
OracleGlobalization.TimeZone by default
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
Value
This property returns the date and time that is stored in the OracleTimeStampTZ
structure in the current time zone.
Declaration
// C#
public DateTime Value{get;}
Property Value
A DateTime in the current time zone.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Year
This property sets the year component of an OracleTimeStampTZ in the current time
zone.
Declaration
// C#
public int Year{get;}
Property Value
A number that represents a year. The range of Year is (-4712 to 9999).
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
OracleTimeStampTZ Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
AddDays
This method adds the supplied number of days to the current instance.
Declaration
// C#
public OracleTimeStampTZ AddDays(double days);
Parameters
■ days
The supplied number of days. Range is (-1,000,000,000 < days < 1,000,000,000)
Return Value
An OracleTimeStampTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
AddHours
This method adds the supplied number of hours to the current instance.
Declaration
// C#
public OracleTimeStampTZ AddHours(double hours);
Parameters
■ hours
The supplied number of hours. Range is (-24,000,000,000 < hours <
24,000,000,000).
Return Value
An OracleTimeStampTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
AddMilliseconds
This method adds the supplied number of milliseconds to the current instance.
Declaration
// C#
public OracleTimeStampTZ AddMilliseconds(double milliseconds);
Parameters
■ milliseconds
The supplied number of milliseconds. Range is (-8.64 * 1016< milliseconds <
8.64 * 1016).
Return Value
An OracleTimeStampTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
AddMinutes
This method adds the supplied number of minutes to the current instance.
Declaration
// C#
public OracleTimeStampTZ AddMinutes(double minutes);
Parameters
■ minutes
The supplied number of minutes. Range is (-1,440,000,000,000 < minutes <
1,440,000,000,000).
Return Value
An OracleTimeStampTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
AddMonths
This method adds the supplied number of months to the current instance.
Declaration
// C#
public OracleTimeStampTZ AddMonths(long months);
Parameters
■ months
The supplied number of months. Range is (-12,000,000,000 < months <
12,000,000,000).
Return Value
An OracleTimeStampTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
AddNanoseconds
This method adds the supplied number of nanoseconds to the current instance.
Declaration
// C#
public OracleTimeStampTZ AddNanoseconds(long nanoseconds);
Parameters
■ nanoseconds
The supplied number of nanoseconds.
Return Value
An OracleTimeStampTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
AddSeconds
This method adds the supplied number of seconds to the current instance.
Declaration
// C#
public OracleTimeStampTZ AddSeconds(double seconds);
Parameters
■ seconds
The supplied number of seconds. Range is (-8.64 * 1013< seconds < 8.64 * 1013).
Return Value
An OracleTimeStampTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
AddYears
This method adds the supplied number of years to the current instance
Declaration
// C#
public OracleTimeStampTZ AddYears(int years);
Parameters
■ years
The supplied number of years. Range is (-999,999,999 <= years < = 999,999,999).
Return Value
An OracleTimeStampTZ.
Exceptions
OracleNullValueException - The current instance has a null value.
ArgumentOutofRangeException - The argument value is out of the specified
range.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
CompareTo
This method compares the current OracleTimeStampTZ 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 to the current OracleTimeStampTZ instance.
Return Value
The method returns a number that is:
Less than zero: if the current OracleTimeStampTZ instance value is less than that of
obj.
Zero: if the current OracleTimeStampTZ instance and obj values are equal.
Greater than zero: if the current OracleTimeStampTZ instance value is greater than
that of obj.
Implements
IComparable
Exceptions
ArgumentException - The obj is not of type OracleTimeStampTZ.
Remarks
The following rules apply to the behavior of this method.
■ The comparison must be between OracleTimeStampTZs. For example,
comparing an OracleTimeStampTZ instance with an OracleBinary instance is
not allowed. When an OracleTimeStampTZ is compared with a different type,
an ArgumentException is thrown.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
Equals
Overrides Object
This method determines whether or not an object has the same date and time as the
current OracleTimeStampTZ instance.
Declaration
// C#
public override bool Equals(object obj);
Parameters
■ obj
The object being compared to the current OracleTimeStampTZ instance.
Return Value
Returns true if the obj is of type OracleTimeStampTZ and represents the same
date and time; otherwise, returns false.
Remarks
The following rules apply to the behavior of this method.
■ Any OracleTimeStampTZ that has a value is greater than an
OracleTimeStampTZ that has a null value.
■ Two OracleTimeStampTZs that contain a null value are equal.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
GetDaysBetween
This method subtracts an OracleTimeStampTZ value from the current instance and
returns an OracleIntervalDS that represents the time interval.
Declaration
// C#
public OracleIntervalDS GetDaysBetween(OracleTimeStampTZ value1);
Parameters
■ value1
The OracleTimeStampTZ value being subtracted.
Return Value
An OracleIntervalDS that represents the interval between two
OracleTimeStampTZ values.
Remarks
If either the current instance or the parameter has a null value, the returned
OracleIntervalDS has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
GetHashCode
Overrides Object
This method returns a hash code for the OracleTimeStampTZ instance.
Declaration
// C#
public override int GetHashCode();
Return Value
A number that represents the hash code.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
GetTimeZoneOffset
This method gets the time zone portion in hours and minutes of the current
OracleTimeStampTZ.
Declaration
// C#
public TimeSpan GetTimeZoneOffset();
Return Value
A TimeSpan.
Exceptions
OracleNullValueException - The current instance has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
GetYearsBetween
This method subtracts an OracleTimeStampTZ value from the current instance and
returns an OracleIntervalYM that represents the time interval.
Declaration
// C#
public OracleIntervalYM GetYearsBetween(OracleTimeStampTZ val);
Parameters
■ val
The OracleTimeStampTZ value being subtracted.
Return Value
An OracleIntervalYM that represents the interval between two
OracleTimeStampTZ values.
Remarks
If either the current instance or the parameter has a null value, the returned
OracleIntervalYM has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
ToLocalTime
This method converts the current OracleTimeStampTZ instance to local time.
Declaration
// C#
public OracleTimeStampLTZ ToLocalTime();
Return Value
An OracleTimeStampLTZ that contains the date and time, which is normalized to
the client local time zone, in the current instance.
Remarks
If the current instance has a null value, the returned OracleTimeStampLTZ has a null
value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
ToOracleDate
This method converts the current OracleTimeStampTZ structure to an OracleDate
structure.
Declaration
// C#
public OracleDate ToOracleDate();
Return Value
The returned OracleDate contains the date and time in the current instance, but the
time zone information in the current instance is truncated
Remarks
The precision of the OracleTimeStampTZ value can be lost during the conversion,
and the time zone information in the current instance is truncated.
If the current instance has a null value, the value of the returned OracleDate
structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
ToOracleTimeStampLTZ
This method converts the current OracleTimeStampTZ structure to an
OracleTimeStampLTZ structure.
Declaration
// C#
public OracleTimeStampLTZ ToOracleTimeStampLTZ();
Return Value
The returned OracleTimeStampLTZ structure contains the date and time, which is
normalized to the client local time zone, in the current instance.
Remarks
If the value of the current instance has a null value, the value of the returned
OracleTimeStampLTZ structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
ToOracleTimeStamp
This method converts the current OracleTimeStampTZ structure to an
OracleTimeStamp structure.
Declaration
// C#
public OracleTimeStamp ToOracleTimeStamp();
Return Value
The returned OracleTimeStamp contains the date and time in the current instance,
but the time zone information is truncated.
Remarks
If the value of the current instance has a null value, the value of the returned
OracleTimeStamp structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
ToString
Overrides Object
This method converts the current OracleTimeStampTZ structure to a string.
Declaration
// C#
public override string ToString();
Return Value
A string that represents the same date and time as the current
OracleTimeStampTZ structure.
Remarks
The returned value is a string representation of an OracleTimeStampTZ in the
format specified by the OracleGlobalization.TimeStampTZFormat property of
the thread. The names and abbreviations used for months and days are in the
language specified by the OracleGlobalization.DateLanguage and the
OracleGlobalization.Calendar properties of the thread. 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()
{
// Set the nls parameters for the current thread
OracleGlobalization info = OracleGlobalization.GetClientInfo();
info.TimeZone = "US/Eastern";
info.TimeStampFormat = "DD-MON-YYYY HH:MI:SS.FF AM";
info.TimeStampTZFormat = "DD-MON-YYYY HH:MI:SS.FF AM TZR";
OracleGlobalization.SetThreadInfo(info);
// Prints "US/Pacific"
Console.WriteLine("tstz1.TimeZone = " + tstz1.TimeZone);
// Prints "US/Eastern"
Console.WriteLine("tstz2.TimeZone = " + tstz2.TimeZone);
// Prints 3
Console.WriteLine("idsDiff.Hours = " + idsDiff.Hours);
// Prints 0
Console.WriteLine("idsDiff.Minutes = " + idsDiff.Minutes);
}
}
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
■ "OracleGlobalization Class" on page 10-2
■ "Globalization Support" on page 3-110
ToUniversalTime
This method converts the current datetime to Coordinated Universal Time (UTC).
Declaration
// C#
public OracleTimeStampTZ ToUniversalTime();
Return Value
An OracleTimeStampTZ structure.
Remarks
If the current instance has a null value, the value of the returned
OracleTimeStampTZ structure has a null value.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTimeStampTZ Structure
■ OracleTimeStampTZ Members
INullable Interface
The INullable interface is used to determine whether or not an ODP.NET type has a
NULL value.
Declaration
// C#
public interface INullable
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ INullable Interface Members
■ INullable Interface Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ INullable Interface
IsNull
This property indicates whether or not the ODP.NET type has a NULL value.
Declaration
// C#
bool IsNull {get;}
Property Value
Returns true if the ODP.NET type has a NULL value; otherwise, returns false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ INullable Interface
■ INullable Interface Members
Exceptions
OracleTypeException Class
The OracleTypeException is the base exception class for handling exceptions that
occur in the ODP.NET Types classes.
Class Inheritance
System.Object
System.Exception
System.SystemException
Oracle.DataAccess.Types.OracleTypeException
Declaration
// C#
public class OracleTypeException : SystemException
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Members
■ OracleTypeException Constructors
■ OracleTypeException Static Methods
■ OracleTypeException Properties
■ OracleTypeException Methods
OracleTypeException Members
OracleTypeException Constructors
The OracleTypeException constructors are listed in Table 15–1.
OracleTypeException Properties
The OracleTypeException properties are listed in Table 15–3.
OracleTypeException Methods
The OracleTypeException methods are listed in Table 15–4.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
OracleTypeException Constructors
Overload List:
■ OracleTypeException(string)
This constructor creates a new instance of the OracleTypeException class with
the specified error message, errMessage.
■ OracleTypeException(SerializationInfo, StreamingContext)
This constructor creates a new instance of the OracleTypeException class with
the specified serialization information, si, and the specified streaming context, sc.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
OracleTypeException(string)
This constructor creates a new instance of the OracleTypeException class with the
specified error message, errMessage.
Declaration
// C#
public OracleTypeException (string errMessage);
Parameters
■ errMessage
The specified error message.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
OracleTypeException(SerializationInfo, StreamingContext)
This constructor creates a new instance of the OracleTypeException class with the
specified serialization information, si, and the specified streaming context, sc.
Declaration
// C#
protected OracleTypeException (SerializationInfo si, StreamingContext sc);
Parameters
■ si
The specified serialization information.
■ sc
The specified streaming context.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
OracleTypeException Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
Message
Overrides Exception
This property specifies the error messages that occur in the exception.
Declaration
// C#
public override string Message {get;}
Property Value
An error message.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
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
Oracle Data Provider for .NET.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
OracleTypeException Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
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 fully qualified name of this exception.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTypeException Class
■ OracleTypeException Members
OracleNullValueException Class
Class Inheritance
System.Object
System.Exception
System.SystemException
System.OracleTypeException
Oracle.DataAccess.Types.OracleNullValueException
Declaration
// C#
public sealed class OracleNullValueException : OracleTypeException
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleNullValueException Members
■ OracleNullValueException Constructors
■ OracleNullValueException Static Methods
■ OracleNullValueException Properties
■ OracleNullValueException Methods
OracleNullValueException Members
OracleNullValueException Constructors
The OracleNullValueException constructors are listed in Table 15–8.
OracleNullValueException Properties
The OracleNullValueException properties are listed in Table 15–10.
OracleNullValueException Methods
The OracleNullValueException methods are listed in Table 15–11.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleNullValueException Class
OracleNullValueException Constructors
Overload List:
■ OracleNullValueException()
This constructor creates a new instance of the OracleNullValueException
class with its default properties.
■ OracleNullValueException(string)
This constructor creates a new instance of the OracleNullValueException
class with the specified error message, errMessage.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleNullValueException Class
■ OracleNullValueException Members
OracleNullValueException()
This constructor creates a new instance of the OracleNullValueException class
with its default properties.
Declaration
// C#
public OracleNullValueException();
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleNullValueException Class
■ OracleNullValueException Members
OracleNullValueException(string)
This constructor creates a new instance of the OracleNullValueException class
with the specified error message, errMessage.
Declaration
// C#
public OracleNullValueException (string errMessage);
Parameters
■ errMessage
The specified error message.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleNullValueException Class
■ OracleNullValueException Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleNullValueException Class
■ OracleNullValueException Members
OracleNullValueException Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleNullValueException Class
■ OracleNullValueException Members
OracleNullValueException Methods
OracleTruncateException Class
Class Inheritance
System.Object
System.Exception
System.SystemException
System.OracleTypeException
Oracle.DataAccess.Types.OracleTruncateException
Declaration
// C#
public sealed class OracleTruncateException : OracleTypeException
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTruncateException Members
■ OracleTruncateException Constructors
■ OracleTruncateException Static Methods
■ OracleTruncateException Properties
■ OracleTruncateException Methods
OracleTruncateException Members
OracleTruncateException Constructors
The OracleTruncateException constructors are listed in Table 15–15.
OracleTruncateException Properties
The OracleTruncateException properties are listed in Table 15–17.
OracleTruncateException Methods
The OracleTruncateException methods are listed in Table 15–18.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTruncateException Class
OracleTruncateException Constructors
Overload List:
■ OracleTruncateException()
This constructor creates a new instance of the OracleTruncateException class
with its default properties.
■ OracleTruncateException(string)
This constructor creates a new instance of the OracleTruncateException class
with the specified error message, errMessage.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTruncateException Class
■ OracleTruncateException Members
OracleTruncateException()
This constructor creates a new instance of the OracleTruncateException class
with its default properties.
Declaration
// C#
public OracleTruncateException();
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTruncateException Class
■ OracleTruncateException Members
OracleTruncateException(string)
This constructor creates a new instance of the OracleTruncateException class
with the specified error message, errMessage.
Declaration
// C#
public OracleTruncateException (string errMessage);
Parameters
■ errMessage
The specified error message.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTruncateException Class
■ OracleTruncateException Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTruncateException Class
■ OracleTruncateException Members
OracleTruncateException Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTruncateException Class
■ OracleTruncateException Members
OracleTruncateException Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleTruncateException Class
■ OracleTruncateException Members
This chapter describes the object-related classes and interfaces in the Oracle Data
Provider for .NET that provide support for Oracle user-defined data types (UDT).
Samples are provided in the ORACLE_BASE\ORACLE_
HOME\ODP.NET\Samples\UDT directory.
■ OracleCustomTypeMappingAttribute Class
■ OracleObjectMappingAttribute Class
■ OracleArrayMappingAttribute Class
■ IOracleCustomType Interface
■ IOracleCustomTypeFactory Interface
■ IOracleArrayTypeFactory Interface
■ OracleUdt Class
■ OracleRef Class
■ OracleUdtFetchOption Enumeration
■ OracleUdtStatus Enumeration
OracleCustomTypeMappingAttribute Class
Class Inheritance
System.Object
System.Attribute
System.OracleCustomTypeMappingAttribute
Declaration
// C#
[AttributeUsageAttribute(AttributeTargets.Class|AttributeTargets.Struct,
AllowMultiple=false, Inherited=true)]
public sealed class OracleCustomTypeMappingAttribute : Attribute
Remarks
The OracleCustomTypeMapping attribute must be specified on the custom type
factory class to indicate the Oracle UDT that the corresponding custom type
represents. The Oracle UDT may be specified in the form schema_name.type_name.
For each Oracle UDT that the application uses, there must be a unique custom type
factory, as follows:
■ Oracle Object Types
The custom type factory must return a custom type that cannot be used to
represent any other Oracle Object Type.
■ Oracle Collection Types
The custom type factory may return a custom type that can be used by other
Oracle Collection Types. This is common when an array type is used to represent
an Oracle Collection, that is, when an int[] is used to represent a collection of
NUMBERs.
If the OracleCustomTypeMappingAttribute is not specified, then custom type
mappings must be specified through an XML configuration file, for example,
app.config for Windows applications or the web.config for web applications, and
the machine.config
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleCustomTypeMappingAttribute Members
■ OracleCustomTypeMappingAttribute Constructors
■ OracleCustomTypeMappingAttribute Static Methods
■ OracleCustomTypeMappingAttribute Methods
OracleCustomTypeMappingAttribute Members
OracleCustomTypeMappingAttribute Constructors
OracleCustomTypeMappingAttribute constructors are listed in Table 16–1.
OracleCustomTypeMappingAttribute Properties
OracleCustomTypeMappingAttribute properties are listed in Table 16–3.
OracleCustomTypeMappingAttribute Methods
OracleCustomTypeMappingAttribute methods are listed in Table 16–4.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleCustomTypeMappingAttribute Class
OracleCustomTypeMappingAttribute Constructors
Overload List:
■ OracleCustomTypeMappingAttribute(string)
This constructor creates and initializes an
OracleCustomTypeMappingAttribute using the specified Oracle
user-defined type name.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleCustomTypeMappingAttribute Class
■ OracleCustomTypeMappingAttribute Methods
OracleCustomTypeMappingAttribute(string)
This constructor creates and initializes an OracleCustomTypeMappingAttribute
using the specified Oracle user-defined type name.
Declaration
// C#
public OracleCustomTypeMappingAttribute(string udtTypeName)
Parameters
■ udtTypeName
The Oracle user-defined type name that the custom class maps to.
Remarks
The udtTypeName parameter is case-sensitive. The udtTypeName is specified in the
form of schema_name.type_name.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleCustomTypeMappingAttribute Class
■ OracleCustomTypeMappingAttribute Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleCustomTypeMappingAttribute Class
■ OracleCustomTypeMappingAttribute Members
OracleCustomTypeMappingAttribute Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleCustomTypeMappingAttribute Class
■ OracleCustomTypeMappingAttribute Members
UdtTypeName
This property specifies the Oracle user-defined type name that the custom class maps
to.
Declaration
// C#
public string UdtTypeName {get; set;}
Property Value
A string that represents an Oracle user-defined type name.
Remarks
UdtTypeName is case-sensitive. It is specified in the form of schema_name.type_
name.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleCustomTypeMappingAttribute Class
■ OracleCustomTypeMappingAttribute Members
OracleCustomTypeMappingAttribute Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleCustomTypeMappingAttribute Class
■ OracleCustomTypeMappingAttribute Members
OracleObjectMappingAttribute Class
Class Inheritance
System.Object
System.Attribute
System.OracleObjectMappingAttribute
Declaration
// C#
[AttributeUsageAttribute(AttributeTargets.Field|AttributeTargets.Property,
AllowMultiple=false, Inherited=true)]
Remarks
The OracleObjectMappingAttribute is specified on members of a custom type
that represent an Oracle object type. This attribute must specify the name or
zero-based index of the attribute in the Oracle object that the custom class field or
property maps to. This also allows the custom type to declare field or property names
which differ from the Oracle Object type.
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Members
■ OracleObjectMappingAttribute Constructors
■ OracleObjectMappingAttribute Static Methods
■ OracleObjectMappingAttribute Properties
■ OracleObjectMappingAttribute Methods
OracleObjectMappingAttribute Members
OracleObjectMappingAttribute Constructors
OracleObjectMappingAttribute constructors are listed in Table 16–8.
OracleObjectMappingAttribute Properties
OracleObjectMappingAttribute properties are listed in Table 16–10.
OracleObjectMappingAttribute Methods
OracleObjectMappingAttribute methods are listed in Table 16–11.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
OracleObjectMappingAttribute Constructors
Overload List:
■ OracleObjectMappingAttribute(string)
This constructor creates and initializes an OracleObjectMappingAttribute
object with the specified Oracle Object attribute name.
■ OracleObjectMappingAttribute(int)
This constructor creates and initializes an OracleObjectMappingAttribute
with the specified Oracle Object attribute index.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
■ OracleObjectMappingAttribute Members
OracleObjectMappingAttribute(string)
This constructor creates and initializes an OracleObjectMappingAttribute object
with the specified Oracle Object attribute name.
Declaration
// C#
public OracleObjectMappingAttribute(string attrName);
Parameters
■ attrName
The name of the Oracle Object attribute to map to.
Remarks
The attrName parameter is case-sensitive.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
■ OracleObjectMappingAttribute Members
OracleObjectMappingAttribute(int)
This constructor creates and initializes an OracleObjectMappingAttribute object
with the specified Oracle Object attribute index.
Declaration
// C#
public OracleObjectMappingAttribute(int attrIndex);
Parameters
■ attrIndex
The zero-based index of the Oracle Object attribute to map to.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
■ OracleObjectMappingAttribute Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
■ OracleObjectMappingAttribute Members
OracleObjectMappingAttribute Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
■ OracleObjectMappingAttribute Members
AttributeIndex
This property specifies the index of the Oracle Object attribute that must be retrieved.
Declaration
// C#
public int AttributeIndex {get;}
Property Value
The zero-based index of an Oracle Object type attribute.
Remarks
The AttributeIndex property specifies the index of the Oracle Object type attribute
that the custom class field or property maps to. This allows the custom class to declare
fields or property names that differ from the Oracle object.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
■ OracleObjectMappingAttribute Members
AttributeName
This property specifies the name of the Oracle Object attribute that must be retrieved.
Declaration
// C#
public string AttributeName {get;}
Property Value
The name of an attribute of an Oracle Object type.
Remarks
The AttributeName property specifies name of the attribute in the Oracle Object
type that the custom class field or property maps to. This allows the custom class to
declare field or property names that differ from the Oracle object.
The specified attribute name is case-sensitive.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
■ OracleObjectMappingAttribute Members
OracleObjectMappingAttribute Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleObjectMappingAttribute Class
■ OracleObjectMappingAttribute Members
OracleArrayMappingAttribute Class
Class Inheritance
System.Object
System.Attribute
System.OracleArrayMappingAttribute
Declaration
[AttributeUsageAttribute(AttributeTargets.Field|AttributeTargets.Property,
AllowMultiple=false, Inherited=true)]
// C#
public sealed class OracleArrayMappingAttribute : Attribute
Remarks
An OracleArrayMappingAttribute object must be specified when a custom type
represents an Oracle Collection. This attribute is applied only to the custom class
member that stores the collection elements.
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleArrayMappingAttribute Members
■ OracleArrayMappingAttribute Constructors
■ OracleArrayMappingAttribute Static Methods
■ OracleArrayMappingAttribute Properties
■ OracleArrayMappingAttribute Methods
OracleArrayMappingAttribute Members
OracleArrayMappingAttribute Constructors
OracleArrayMappingAttribute constructors are listed in Table 16–15.
OracleArrayMappingAttribute Properties
OracleArrayMappingAttribute properties are listed in Table 16–17.
OracleArrayMappingAttribute Methods
OracleArrayMappingAttribute methods are listed in Table 16–18.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleArrayMappingAttribute Class
OracleArrayMappingAttribute Constructors
Overload List:
■ OracleArrayMappingAttribute()
This constructor creates and initializes an OracleArrayMappingAttribute
object.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleArrayMappingAttribute Class
■ OracleArrayMappingAttribute Members
OracleArrayMappingAttribute()
This constructor creates and initializes an OracleArrayMappingAttribute object.
Declaration
// C#
public OracleArrayMappingAttribute();
Remarks
An OracleArrayMappingAttribute object must be applied when a custom class
represents an Oracle Collection type, to specify the custom class field or property that
stores the collection elements.
The OracleArrayMappingAttribute can be applied to only one field or property
in the custom class.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleArrayMappingAttribute Class
■ OracleArrayMappingAttribute Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleArrayMappingAttribute Class
■ OracleArrayMappingAttribute Members
OracleArrayMappingAttribute Properties
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleArrayMappingAttribute Class
■ OracleArrayMappingAttribute Members
OracleArrayMappingAttribute Methods
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleArrayMappingAttribute Class
■ OracleArrayMappingAttribute Members
IOracleCustomType Interface
Declaration
// C#
public interface IOracleCustomType
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomType Members
■ IOracleCustomType Interface Methods
IOracleCustomType Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomType Interface
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomType Interface
■ IOracleCustomType Members
FromCustomObject
This interface method creates an Oracle Object or Collection by setting the attribute or
element values respectively on the specified Oracle UDT.
Declaration
// C#
void FromCustomObject(OracleConnection con, IntPtr pUdt);
Parameters
■ con
An OracleConnection instance.
■ pUdt
An opaque pointer to the Oracle Object or Collection to be created.
Remarks
The FromCustomObject method is used to build an Oracle Object or Collection from
a custom object by setting attribute or element values respectively through the
OracleUdt.SetValue method.
The OracleUdt.SetValue method is invoked as follows:
■ Oracle Object Type
For a custom type that represents an Oracle Object Type, the
OracleUdt.SetValue method must be invoked for each non-NULL attribute
value that needs to be set.
■ Oracle Collection Type
For a custom type that represents an Oracle Collection Type, a single call to
OracleUdt.SetValue method specifies the collection element values.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomType Interface
■ IOracleCustomType Members
ToCustomObject
This interface initializes a custom object using the specified Oracle UDT.
Declaration
// C#
void ToCustomObject (OracleConnection con, IntPtr pUdt);
Parameters
■ con
An OracleConnection instance.
■ pUdt
An opaque pointer to the Oracle UDT.
Remarks
The ToCustomObject method is used to initialize a custom object from the specified
Oracle Object or Collection by retrieving attribute or element values respectively
through the OracleUdt.GetValue method.
The OracleUdt.GetValue method is invoked as follows:
■ Oracle Object Type
For a custom type that represents an Oracle Object Type, the
OracleUdt.GetValue method must be invoked for each attribute value to be
retrieved.
■ For a custom type that represents an Oracle Collection Type, a single call to
OracleUdt.GetValue method retrieves the collection element values.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomType Interface
■ IOracleCustomType Members
IOracleCustomTypeFactory Interface
Declaration
// C#
public interface IOracleCustomTypeFactory
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomTypeFactory Members
■ IOracleCustomTypeFactory Interface Methods
IOracleCustomTypeFactory Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomTypeFactory Interface
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomTypeFactory Interface
■ IOracleCustomTypeFactory Members
CreateObject
This interface method returns a new custom object to represent an Oracle Object or
Collection.
Declaration
// C#
IOracleCustomType CreateObject();
Return Value
An IOracleCustomType object.
Remarks
The CreateObject method is used to create a new instance of a custom object to
represent an Oracle Object or Collection.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleCustomTypeFactory Interface
■ IOracleCustomTypeFactory Members
IOracleArrayTypeFactory Interface
Declaration
// C#
public interface IOracleArrayTypeFactory
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleArrayTypeFactory Members
■ IOracleArrayTypeFactory Interface Methods
IOracleArrayTypeFactory Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleArrayTypeFactory Interface
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleArrayTypeFactory Interface
■ IOracleArrayTypeFactory Members
CreateArray
This interface method returns a new array of the specified length to store Oracle
Collection elements.
Declaration
// C#
Array CreateArray(int numElems);
Parameters
■ numElems
The number of collection elements to be returned.
Return Value
A System.Array object.
Remarks
An Oracle Collection Type may be represented in either of the following ways:
■ As an array of the appropriate type. The type must be able to represent a collection
element.
■ As a Custom Type that contains an array of the appropriate type.
In both cases, the CreateArray method creates an array of the specified length to
store the collection elements.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleArrayTypeFactory Interface
■ IOracleArrayTypeFactory Members
CreateStatusArray
This method returns a newly allocated OracleUdtStatus array of the specified
length that will be used to store the null status of the collection elements.
Declaration
// C#
Array CreateStatusArray(int numElems);
Parameters
■ numElems
The number of collection elements to be returned.
Return Value
A multi-dimensional OracleUdtStatus array as a System.Array.
Remarks
An Oracle Collection Type can be represented in the following ways:
■ As an array of the appropriate type. The type must be able to represent a collection
element.
■ As a Custom Type that contains an array of the appropriate type.
In both cases, the CreateStatusArray method creates an OracleUdtStatus array
of the specified length that stores the null status of the collection elements.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ IOracleArrayTypeFactory Interface
■ IOracleArrayTypeFactory Members
■ "OracleUdtFetchOption Enumeration" on page 16-73
OracleUdt Class
The OracleUdt class defines static methods that are used when converting between
Custom Types and Oracle UDTs and vice-versa.
Class Inheritance
System.Object
System.OracleUdt
Declaration
public sealed class OracleUdt
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
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Members
■ OracleUDT Static Methods
OracleUdt Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
GetValue
GetValue methods get the attributes or elements from the specified Oracle UDT.
Overload List:
■ GetValue(OracleConnection, IntPt, string)
This method gets the attributes or elements from the specified Oracle UDT, using
the specified attribute name.
■ GetValue(OracleConnection, IntPtr, int)
This method gets the attribute or elements from the specified Oracle UDT, using
the specified index.
■ GetValue(OracleConnection, IntPtr, string, out object)
This method returns either the elements of the specified collection attribute of the
specified Oracle Object or the elements of the specified Oracle Collection.
■ GetValue(OracleConnection, IntPtr, int, out object)
This method returns either the elements of the specified collection attribute of the
specified Oracle Object or the elements of the specified Oracle Collection.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ "OracleUdt Members"
Declaration
public static object GetValue(OracleConnection con, IntPtr pUdt, string attrName);
Parameters
■ con
An OracleConnection instance.
■ pUdt
A pointer to an Oracle UDT.
■ attrName
The case-sensitive name of the attribute to be retrieved. Null is specified for
retrieving collection elements from a Custom Type that represents an Oracle
Collection.
Return Value
An object representing the returned attribute or collection elements.
Exceptions
ArgumentException - The specified name is not a valid attribute name.
Remarks
The IOracleCustomType.ToCustomObject method invokes
OracleUdt.GetValue method passing it the con and pUdt parameters. The
OracleUdt.GetValue method returns these types of object:
■ Oracle Object Type
For a Custom Type that represents an Oracle Object Type, the type returned for a
specified attribute name is the type of the member in the custom class or struct
that is mapped to the attribute using the OracleObjectMappingAttribute
object.
■ Oracle Collection Type
For a Custom Type that represents an Oracle Collection Type, the type returned is
the type of the member in the custom class or struct to which the
OracleArrayMappingAttribute object is applied.
In the case of NULL attribute values, the appropriate null representation of the type is
returned. For example, for attributes that are represented as Custom Types and
Provider Specific Types, the static Null property of the type is returned. For attributes
that are represented as Nullable types, for example, System.String and
System.Array Types, null is returned, and for all other remaining built-in types such
as Int32 and DateTime DBNull.Value is returned.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
■ "OracleUdtFetchOption Enumeration" on page 16-73
Declaration
// C#
public static object GetValue(OracleConnection con, IntPtr pUdt, int attrIndex,);
Parameters
■ con
An OracleConnection instance.
■ pUdt
A pointer to an Oracle UDT.
■ attrIndex
The zero-based index of the attribute to be retrieved. For retrieving collection
elements from a Custom Type that represents an Oracle Collection, zero must be
specified.
Return Value
An object representing the returned attribute or collection elements.
Exceptions
ArgumentOutOfRangeException - The specified index is not a valid attribute
index.
Remarks
The IOracleCustomType.ToCustomObject method invokes
OracleUdt.GetValue method passing it the con and pUdt parameters. The
OracleUdt.GetValue method returns these types of object:
■ Oracle Object Type
For a Custom Type that represents an Oracle Object Type, the type returned for a
specified attribute index is the type of the member in the custom class or struct
that is mapped to the attribute using the OracleObjectMappingAttribute
object.
■ Oracle Collection Type
For a Custom Type that represents an Oracle Collection Type, the type returned is
the type of the member in the custom class or struct to which the
OracleArrayMappingAttribute object is applied.
In the case of NULL attribute values, the appropriate null representation of the type is
returned. For example, for attributes that are represented as Custom Types and
Provider Specific Types, the static Null property of the type is returned. For attributes
that are represented as Nullable types, for example, System.String and
System.Array Types, null is returned, and for all other remaining built-in types such
as Int32 and DateTime DBNull.Value is returned.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
■ "OracleUdtFetchOption Enumeration" on page 16-73
Declaration
// C#
public static object GetValue(OracleConnection con, IntPtr pUdt, string attrName,
out object statusArray);
Parameters
■ con
An OracleConnection instance.
■ pUdt
An opaque pointer to an Oracle UDT.
■ attrName
The case-sensitive name of the attribute to be retrieved. Null must specified for
retrieving collection elements from a Custom Type that represents an Oracle
Collection.
■ statusArray - The OracleUdtStatus array which returns the null status for
the retrieved collection elements.
Return Value
An object representing the returned attribute or collection elements.
Exceptions
ArgumentException - The specified name is not a valid attribute name.
Remarks
The IOracleCustomType.ToCustomObject method invokes
OracleUdt.GetValue method passing it the con and pUdt parameters. The
OracleUdt.GetValue method returns these types of object:
■ Oracle Object Type
For a Custom Type that represents an Oracle Object Type, the type returned for a
specified attribute name is the type of the member in the custom class or struct
that is mapped to the attribute using the OracleObjectMappingAttribute
object.
■ Oracle Collection Type
For a Custom Type that represents an Oracle Collection Type, the type returned is
the type of the member in the custom class or struct to which the
OracleArrayMappingAttribute object is applied.
In the case of NULL attribute values, the appropriate null representation of the type is
returned. For example, for attributes that are represented as Custom Types and
Provider Specific Types, the static Null property of the type is returned. For attributes
that are represented as Nullable types, for example, System.String and
System.Array Types, null is returned, and for all other remaining built-in types such
as Int32 and DateTime DBNull.Value is returned.
If the collection being returned is not NULL, the output statusArray parameter is
populated with the null status for each of the collection elements.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
■ "OracleUdtFetchOption Enumeration" on page 16-73
Declaration
// C#
public static object GetValue(OracleConnection con, IntPtr pUdt, string attrName,
out object statusArray);
Parameters
■ con
An OracleConnection instance.
■ pUdt
An opaque pointer to an Oracle UDT.
■ attrIndex
The zero-based index of the attribute to be retrieved. For retrieving collection
elements from a Custom Type that represents an Oracle Collection, 0 is specified.
■ statusArray
The OracleUdtStatus array which returns the null status for the retrieved
collection elements.
Return Value
An object representing the returned attribute or collection elements.
Exceptions
ArgumentOutOfRangeException - The specified index is not a valid attribute
index.
Remarks
The IOracleCustomType.ToCustomObject method invokes
OracleUdt.GetValue method passing it the con and pUdt parameters. The
OracleUdt.GetValue method returns these types of object:
■ Oracle Object Type
For a Custom Type that represents an Oracle Object Type, the type returned for a
specified attribute index is the type of the member in the custom class or struct
that is mapped to the attribute using the OracleObjectMappingAttribute
object.
■ Oracle Collection Type
For a Custom Type that represents an Oracle Collection Type, the type returned is
the type of the member in the custom class or struct to which the
OracleArrayMappingAttribute object is applied.
In the case of NULL attribute values, the appropriate null representation of the type is
returned. For example, for attributes that are represented as Custom Types and
Provider Specific Types, the static Null property of the type is returned. For attributes
that are represented as Nullable types, for example, System.String and
System.Array Types, null is returned, and for all other remaining built-in types such
as Int32 and DateTime DBNull.Value is returned.
If the collection being returned is not NULL, the output statusArray parameter is
populated with the null status for each of the collection elements.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
■ "OracleUdtFetchOption Enumeration" on page 16-73
IsDBNull
IsDBNull methods indicate whether or not the specified attribute being retrieved is
NULL.
Overload List:
■ IsDBNull(OracleConnection, IntPtr, string)
This method indicates whether or not the attribute being retrieved, specified by
OracleConnection, pointer, and attribute name, is NULL.
■ IsDBNull(OracleConnection, IntPtr, int)
This method indicates whether or not the attribute being retrieved, specified by
OracleConnection, pointer, and attribute index, is NULL.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
■ "OracleUdtFetchOption Enumeration" on page 16-73
Declaration
// C#
public static bool IsDBNull(OracleConnection con, IntPtr pUdt, string attrName);
Parameters
■ con
An OracleConnection instance.
■ pUdt
A pointer to an Oracle UDT.
■ attrName
The case-sensitive name of the attribute.
Return Value
True if the specified attribute is NULL; otherwise, false.
Exceptions
ArgumentException - The specified name is not a valid attribute name.
Remarks
This method is invoked from the IOracleCustomType.ToCustomObject method.
The con and pUdt parameter is passed from the
IOracleCustomType.ToCustomObject method to the OracleUdt.IsDBNull
method. The attrName parameter is case-sensitive.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
Declaration
// C#
public static bool IsDBNull(OracleConnection con, IntPtr pUdt, int attrIndex);
Parameters
■ con
An OracleConnection instance.
■ pUdt
Return Value
True if the specified attribute is NULL; otherwise, false.
Exceptions
ArgumentOutOfRangeException - The specified index is not a valid attribute index
Remarks
This method is invoked from the IOracleCustomType.ToCustomObject method.
The con and pUdt parameter is passed from the
IOracleCustomType.ToCustomObject method to the OracleUdt.IsDBNull
method.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
SetValue
SetValue methods set the attributes or elements on the specified Oracle UDT.
Overload List:
■ SetValue(OracleConnection, IntPtr, string, object)
This method sets the attribute or elements on the specified Oracle UDT, using the
specified attribute name and value.
■ SetValue(OracleConnection, IntPtr, int, object)
This method sets the attribute or elements on the specified Oracle UDT, using the
specified index and value.
■ SetValue(OracleConnection, IntPtr, string, object, object)
This method sets either the specified collection attribute of the specified Oracle
Object or elements of the specified Oracle Collection, to the specified value using
the supplied null status of the collection elements.
■ SetValue(OracleConnection, IntPtr, int, object, object)
This method sets either the specified collection attribute of the specified Oracle
Object or elements of the specified Oracle Collection, to the specified value using
the supplied null status of the collection elements.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ OracleUdt Members
Declaration
// C#
public static void SetValue(OracleConnection con, IntPtr pUdt, string attrName,
object value);
Parameters
■ con
An OracleConnection instance.
■ pUdt
An opaque pointer to an Oracle UDT.
■ attrName
The name of the attribute to be set. Specify null for setting collection elements
from a Custom Type that represents an Oracle Collection.
■ value
The attribute or collection value to be set.
Exceptions
ArgumentException - The specified value is not of the appropriate type.
Remarks
The IOracleCustomType.FromCustomObject method invokes
OracleUdt.SetValue method passing it the con and pUdt parameters. The
OracleUdt.SetValue method returns these types of object:
■ Oracle Object Type
For a Custom Type that represents an Oracle Object Type, the type accepted for a
specified attribute name is the type of the member in the custom class or struct
that is mapped to the attribute using the OracleObjectMappingAttribute
object.
■ Oracle Collection Type
For a Custom Type that represents an Oracle Collection Type, the type accepted is
the type of the member in the custom class or struct to which the
OracleArrayMappingAttribute object is applied.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ "OracleUdt Members"
Declaration
// C#
public static void SetValue(OracleConnection con, IntPtr pUdt, int attrIndex,
object value);
Parameters
■ con
An OracleConnection instance.
■ pUdt
An opaque pointer to an Oracle UDT.
■ attrIndex
The index of the attribute to be set. Specify 0 for setting collection elements from a
Custom Type that represents an Oracle Collection.
■ value
The attribute or collection value to be set.
Exceptions
ArgumentException - The specified value is not of the appropriate type.
Remarks
The IOracleCustomType.FromCustomObject method invokes
OracleUdt.SetValue method passing it the con and pUdt parameters. The
OracleUdt.SetValue method returns these types of object:
■ Oracle Object Type
For a Custom Type that represents an Oracle Object Type, the type accepted for a
specified attribute index is the type of the member in the custom class or struct
that is mapped to the attribute using the OracleObjectMappingAttribute
object.
■ Oracle Collection Type
For a Custom Type that represents an Oracle Collection Type, the type accepted is
the type of the member in the custom class or struct to which the
OracleArrayMappingAttribute object is applied.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ "OracleUdt Members"
Declaration
// C#
public static void SetValue(OracleConnection con, IntPtr pUdt, string attrName,
Parameters
■ con
An OracleConnection instance.
■ pUdt
An opaque pointer to an Oracle UDT.
■ attrName
The name of the attribute to be set. Specify null for setting collection elements
from a Custom Type that represents an Oracle Collection.
■ value
The attribute or collection value to be set.
■ statusArray
The null status for the collection elements.
Exceptions
ArgumentException - The specified value is not of the appropriate type.
Remarks
The IOracleCustomType.FromCustomObject method invokes
OracleUdt.SetValue method passing it the con and pUdt parameters. The
OracleUdt.SetValue method returns these types of object:
■ Oracle Object Type
For a Custom Type that represents an Oracle Object Type, the type accepted for a
specified attribute name is the type of the member in the custom class or struct
that is mapped to the attribute using the OracleObjectMappingAttribute
object.
■ Oracle Collection Type
For a Custom Type that represents an Oracle Collection Type, the type accepted is
the type of the member in the custom class or struct to which the
OracleArrayMappingAttribute object is applied.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ "OracleUdt Members"
Declaration
// C#
public static void SetValue(OracleConnection con, IntPtr pUdt, int attrIndex,
Parameters
■ con
An OracleConnection instance.
■ pUdt
An opaque pointer to an Oracle UDT.
■ attrIndex
The index of the attribute to be set. Specify 0 for setting collection elements from a
Custom Type that represents an Oracle Collection.
■ value
The attribute or collection value to be set.
■ statusArray
The null status for the collection elements.
Exceptions
ArgumentException - The specified value is not of the appropriate type.
Remarks
The IOracleCustomType.FromCustomObject method invokes
OracleUdt.SetValue method passing it the con and pUdt parameters. The
OracleUdt.SetValue method returns these types of object:
■ Oracle Object Type
For a Custom Type that represents an Oracle Object Type, the type accepted for a
specified attribute index is the type of the member in the custom class or struct
that is mapped to the attribute using the OracleObjectMappingAttribute
object.
■ Oracle Collection Type
For a Custom Type that represents an Oracle Collection Type, the type accepted is
the type of the member in the custom class or struct to which the
OracleArrayMappingAttribute object is applied.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleUdt Class
■ "OracleUdt Members"
OracleRef Class
Class Inheritance
System.Object
System.MarshalByRefObject
Oracle.DataAccess.Types.OracleRef
Declaration
// C#
public sealed class OracleRef : MarshalByRefObject,ICloneable, IDisposable,
INullable
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
If two or more OracleRef objects that refer to the same Oracle object in the database
are retrieved through the same OracleConnection, then their operations on the
referenced object must be synchronized.
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Members
■ OracleRef Constructors
■ OracleRef Static Methods
■ OracleRef Instance Properties
■ Oracle Ref Instance Methods
OracleRef Members
OracleRef Constructors
OracleRef constructors are listed in Table 16–30.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
OracleRef Constructors
Overload List:
■ OracleRef(OracleConnection, string)
This constructor creates an instance of the OracleRef class with a connection and
a HEX string that represents an REF instance in the database.
■ OracleRef(OracleConnection, string, string)
This constructor creates an instance of the OracleRef class using the specified
OracleConnection object, user-defined type name, and an object table name
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
OracleRef(OracleConnection, string)
This constructor creates an instance of the OracleRef class with a connection and a
HEX string that represents an REF instance in the database.
Declaration
// C#
public OracleRef(OracleConnection con, string hexStr);
Parameters
■ con
An OracleConnection instance.
■ hexStr
A HEX string that represents an REF instance in the database.
Exceptions
ArgumentException - The HEX string does not represent a valid REF in the
database.
ArgumentNullException - The connection or HEX string is null.
InvalidOperationException - The OracleConnection object is not open.
Remarks
When an OracleRef instance is created, it is referenced to a specific table in the
database.
The connection must be opened explicitly by the application. OracleRef does not
open the connection implicitly.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Declaration
// C#
public OracleRef(OracleConnection con, string udtTypeName, string objTabName);
Parameters
■ con
An OracleConnection instance.
■ udtTypeName
A user-defined type name.
■ objTabName
An object table name.
Exceptions
ArgumentException - The object type name or the object table name is not valid.
ArgumentNullException - The object type name or the table name is null.
InvalidOperationException - The OracleConnection object is not open.
Remarks
When an OracleRef instance is created, this OracleRef instance is associated with
the specific table in the database. In other words, it represents a persistent REF.
This constructor creates a reference to the object table. However, it does not cause any
entries to be made in database tables until the object is flushed to the database, that is,
until the OracleRef.Flush or the OracleConnection.FlushCache method is
called on the OracleRef Connection. Therefore, any operation that attempts to
operate on the database copy of the object before flushing the object, such as, lock the
object or fetch the latest copy of the object from the database, results in an
OracleException.
The connection must be opened explicitly by the application. OracleRef does not
open the connection implicitly.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
■ "FlushCache" on page 5-98
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Null
This static field represents a null value that can be assigned to an OracleRef instance.
Declaration
// C#
public static readonly OracleRef Null;
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Connection
This instance property references the connection used by the OracleRef.
Declaration
// C#
public OracleConnection Connection{get;}
Property Value
An OracleConnection object associated with the REF.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
Once the Dispose method is invoked, this property is set to null.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
HasChanges
This instance property indicates whether or not the object referenced by the Oracle
REF in the object cache has any changes that can be flushed to the database.
Declaration
// C#
public bool HasChanges {get;}
Property Value
Returns true if the object referenced by the Oracle REF in the object cache has any
changes that can be flushed to the database; otherwise, returns false.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
This property returns true if a copy of the referenced object in the object cache is
updated or deleted.
If there is no copy of the referenced object in the object cache, the latest copy of the
referenced object in the database is cached in the object cache and false is returned.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
IsLocked
This instance property indicates whether or not the REF is locked.
Declaration
// C#
public bool IsLocked {get;}
Property Value
Returns true if the REF is locked; otherwise returns false.
Exceptions
ObjectDisposedException - The object is already disposed.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
IsNull
This instance property indicates whether or not the Oracle REF is NULL.
Declaration
// C#
public bool IsNull {get;}
Property Value
Returns true if the REF is NULL; otherwise, returns false.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
If the Oracle REF is NULL, this property returns true. Otherwise, it returns false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
ObjectTableName
This instance property returns the fully-qualified object table name that is associated
with the REF.
Declaration
// C#
public string ObjectTableName{get;}
Property Value
A fully-qualified object table name that is associated with the REF.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
The object table name is in the form schema_Name.Table_Name.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Value
This instance property returns a .NET representation of this Oracle REF.
Declaration
// C#
public string Value{get;}
Property Value
A .NET representation of the Oracle REF.
Exceptions
ObjectDisposedException - The object is already disposed.
Remarks
This property returns a HEX string that represents the REF.
The returned string can be used to create a new OracleRef instance by using the
OracleRef(OracleConnection, string) constructor.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
■ "OracleRef(OracleConnection, string)" on page 16-54
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Clone
This instance method clones the REF.
Declaration
// C#
public OracleRef Clone();
Return Value
A clone of the current instance.
Implements
ICloneable
Exceptions
InvalidOperationException - The associated connection is not open.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Delete
This method deletes the referenced object from the database.
Declaration
// C#
public void Delete(bool bFlush);
Parameters
■ bFlush
A bool that specifies whether or not the REF is flushed immediately.
Remarks
This method marks the specified REF for deletion.
Depending on whether the value of bFlush is set to true or false, the following
occurs:
■ True
The object referenced by the specified REF is deleted immediately from the
database.
Before flushing objects, it is required that the application has explicitly started a
transaction by executing the BeginTransaction method on the
OracleConnection object. This is because if the object being flushed has not
already been locked by the application, an exclusive lock is obtained implicitly for
the object. The lock is only released when the transaction commits or rollbacks.
■ False
The object referenced by the REF is not deleted immediately from the database,
but only when a subsequent Flush method is invoked for the specified REF or the
FlushCache method is invoked on the OracleRef or the FlushCache method
is invoked on the OracleRef connection.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
■ OracleConnection "FlushCache" on page 5-98
Dispose
This instance method releases resources allocated for the OracleRef instance.
Declaration
// C#
Implements
IDisposable
Remarks
The object cannot be reused after it is disposed. Although some properties can still be
accessed, their values may not be up-to-date.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Flush
This instance method flushes changes made on the REF object to the database, such as
updates or deletes.
Declaration
// C#
public void Flush();
Exceptions
InvalidOperationException - The associated connection is not open.
Remarks
Before flushing objects, it is required that the application has explicitly started a
transaction by executing the BeginTransaction method on the
OracleConnection object. This is because if the object being flushed has not already
been locked by the application, an exclusive lock is obtained implicitly for the object.
The lock is only released when the transaction commits or rollbacks.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
GetCustomObject
GetCustomObject methods return the object that the specified REF references as a
custom type.
Overload List
■ GetCustomObject(OracleUdtFetchOption)
This method returns the object that the specified REF references as a custom type
using the specified fetch option.
■ GetCustomObject(OracleUdtFetchOption, int)
This method returns the object that the specified REF references as a custom type
using the specified fetch option and depth level.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
GetCustomObject(OracleUdtFetchOption)
This method returns the object that the specified REF references, as a custom type,
using the specified fetch option.
Declaration
// C#
public object GetCustomObject(OracleUdtFetchOption fetchOption);
Parameters
■ fetchOption
An OracleUdtFetchOption value.
Return Value
A custom object that represents the object that the specified REF references.
Exceptions
InvalidOperationException - The specified connection is not open, or a valid
custom type has not been registered for the type of the referenced object.
Remarks
This method returns a custom type determined by the UDT mappings on the specified
connection.
The connection must be opened explicitly by the application. This method does not
open the connection implicitly.
The application can use the OracleUdtFetchOption method to control the copy of
the Object that is returned according to the specified option:
■ OracleUdtFetchOption.Cache option
If this option is specified, and there is a copy of the referenced object in the object
cache, it is returned immediately. If no cached copy exists, the latest copy of the
referenced object in the database is cached in the object cache and returned.
■ OracleUdtFetchOption.Server option
If this option is specified, the latest copy of the referenced object from the database
is cached in the object cache and returned. If a copy of the referenced object
already exists in the cache, the latest copy overwrites the existing one.
■ OracleUdtFetchOption.TransactionCache option
If this option is specified, and a copy of the referenced object is cached in the
current transaction, the copy is returned. Otherwise, the latest copy of the
referenced object from the database is cached in the object cache and returned. If a
copy of the referenced object already exists in the cache, the latest copy overwrites
the existing one.
Note that if a cached copy of the referenced object was modified before the current
transaction began, that is, if the OracleRef.HasChanges property returns true,
then the Recent option returns the cached copy of the referenced object. Outside
of a transaction, the Recent option behaves like the Any option.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
■ "OracleUdtFetchOption Enumeration" on page 16-73
GetCustomObject(OracleUdtFetchOption, int)
This method returns the object that the specified REF references, as a custom type,
using the specified fetch option and depth level.
Declaration
// C#
public object GetCustomObject(OracleUdtFetchOption fetchOption, int depthLevel);
Parameters
■ fetchOption
An OracleUdtFetchOption value.
■ depthLevel
The number of levels to be fetched for nested REF attributes.
Return Value
A custom object that represents the object that the specified REF references.
Exceptions
InvalidOperationException - The specified connection is not open, or a valid
custom type has not been registered for the type of the referenced object.
Remarks
This method returns a custom type determined by the UDT mappings on the specified
connection.
If the object that the REF references contains nested REF attributes, the depthLevel
can be specified to optimize the subsequent object retrieval. The value of depthLevel
determines the number of levels that are optimized.
For example, if the depthLevel is specified as two, the optimization is applied to all
top-level nested REF attributes in the object being fetched and also to all nested REF
attributes within the objects referenced by the top-level nested REF attributes.
The connection must be opened explicitly by the application. This method does not
open the connection implicitly.
The application can use the OracleUdtFetchOption method to control the copy of
the Object that is returned according to the specified option:
■ OracleUdtFetchOption.Cache option
If this option is specified, and there is a copy of the referenced object in the object
cache, it is returned immediately. If no cached copy exists, the latest copy of the
referenced object in the database is cached in the object cache and returned.
■ OracleUdtFetchOption.Server option
If this option is specified, the latest copy of the referenced object from the database
is cached in the object cache and returned. If a copy of the referenced object
already exists in the cache, the latest copy overwrites the existing one.
■ OracleUdtFetchOption.TransactionCache option
If this option is specified, and a copy of the referenced object is cached in the
current transaction, the copy is returned. Otherwise, the latest copy of the
referenced object from the database is cached in the object cache and returned. If a
copy of the referenced object already exists in the cache, the latest copy overwrites
the existing one.
Note that if a cached copy of the referenced object was modified before the current
transaction began, that is, if the OracleRef.HasChanges property returns true,
then the Recent option returns the cached copy of the referenced object. Outside
of a transaction, the Recent option behaves like the Any option.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
■ "OracleUdtFetchOption Enumeration" on page 16-73
GetCustomObjectForUpdate
GetCustomObjectForUpdate methods return the object that the specified REF
references as a custom type.
■ GetCustomObjectForUpdate(bool)
This method locks the specified REF in the database and returns the object that the
specified REF references as a custom type using the specified wait option.
■ GetCustomObjectForUpdate(bool, int)
This method locks the specified REF in the database and returns the object that the
specified REF references as a custom type using the specified wait option and
depth level.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
GetCustomObjectForUpdate(bool)
This method locks the specified REF in the database and returns the object that the
specified REF references, as a custom type, using the specified wait option.
Declaration
// C#
public object GetCustomObjectForUpdate(bool bWait);
Parameters
■ bWait
Specifies if the REF is to be locked with the no-wait option. If wait is set to true,
this method invocation does not return until the REF is locked.
Return Value
A custom object that represents the object that the specified REF references.
Exceptions
InvalidOperationException - The specified connection is not open, or a valid
custom type has not been registered for type of the referenced object.
OracleException - bWait is set to false, and the lock cannot be acquired.
Remarks
This method returns the latest copy of the referenced object, as a custom type,
determined by the custom types registered on the OracleRef connection.
To be able to release the lock on the REF appropriately after flushing the REF using the
Flush method on the OracleRef or FlushCache method on the
OracleConnection, the application must commit or rollback the transaction.
Therefore, it is required that, before invoking this method, a transaction is explicitly
started by executing the BeginTransaction method on the OracleConnection
object.
This method makes a network round-trip to lock the REF in the database. After this
call, programmers can modify the associated row object exclusively. Then a call to the
Flush method on the OracleRef or FlushCache method on the
OracleConnection flushes the changes to the database.
If true is passed, this method blocks until the lock can be acquired. If false is
passed, this method immediately returns. If the lock cannot be acquired, an
OracleException is thrown.
The connection must be opened explicitly by the application. This method does not
open the connection implicitly.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
GetCustomObjectForUpdate(bool, int)
This method locks the specified REF in the database and returns the object that the
specified REF references, as a custom type, using the specified wait option and depth
level
Declaration
Parameters
■ bWait
A boolean value that specifies if the REF is to be locked with the no-wait option. If
wait is set to true, this method invocation does not return until the REF is locked.
■ depthLevel
The number of levels to be fetched for nested REF attributes.
Return Value
A custom object that represents the object that the specified REF references.
Exceptions
InvalidOperationException - The specified connection is not open, or a valid
custom type has not been registered for type of the referenced object.
OracleException - bWait is set to false, and the lock cannot be acquired.
Remarks
This method returns the latest copy of the referenced object, as a custom type,
determined by the custom types registered on the OracleRef connection.
To be able to release the lock on the REF appropriately after flushing the REF using the
Flush method on the OracleRef or FlushCache method on the
OracleConnection, the application must commit or rollback the transaction.
Therefore, it is required that, before invoking this method, a transaction is explicitly
started by executing the BeginTransaction method on the OracleConnection
object.
This method makes a network round-trip to lock the REF in the database. After this
call, programmers can modify the associated row object exclusively. Then a call to the
Flush method on the OracleRef or FlushCache method on the
OracleConnection flushes the changes to the database.
If true is passed, this method blocks until the lock can be acquired. If false is
passed, this method immediately returns. If the lock cannot be acquired, an
OracleException is thrown.
If the object that the REF references contains nested REF attributes, the depthLevel
can be specified to optimize the subsequent object retrieval. The value of depthLevel
determines the number of levels that are optimized.
For example, if the depthLevel is specified as 2, the optimization is applied to all
top-level nested REF attributes in the object being fetched and also to all nested REF
attributes within the objects referenced by the top-level nested REF attributes.
The connection must be opened explicitly by the application. This method does not
open the connection implicitly.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
IsEqual
This instance method compares two OracleREF objects.
Declaration
// C#
public bool IsEqual(OracleRef oraRef);
Parameters
■ oraRef
The provided OracleRef object.
Return Value
bool
Remarks
This instance method returns true if the OracleRef instance and the OracleRef
parameter both reference the same object. Otherwise, it returns false.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Lock
This instance method locks the REF in the database.
Declaration
// C#
public bool Lock(bool bWait);
Parameters
■ bWait
Specifies if the lock is set to the no-wait option. If bWait is set to true, the
method invocation does not return until the REF is locked.
Return Value
A boolean value that indicates whether or not the lock has been acquired.
Exceptions
InvalidOperationException - The associated connection is not open.
ObjectDisposedException - The object is already disposed.
Remarks
In order for the application to release the lock on the REF appropriately after the
Flush invocation on the OracleRef or FlushCache methods, the application must
commit or rollback the transaction. Therefore, it is required that, before invoking a lock
on an OracleRef object, a transaction is explicitly started by executing the
BeginTransaction method on the OracleConnection object.
This instance method makes a network round-trip to lock the REF in the database.
After this call, programmers can modify the attribute values of the associated row
object exclusively. Then a call to the Flush instance method on the OracleRef or
FlushCache method on the OracleConnection flushes the changes to the
database.
If true is passed, this method blocks, that is, does not return, until the lock is
acquired. Consequently, the return value is always true.
If false is passed, this method immediately returns. The return value indicates true
if the lock is acquired, and false if it is not.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
Update
This method updates the object referenced by the specified REF in the database using
the specified custom object.
Declaration
// C#
public void Update(object customObject, bool bFlush);
Parameters
■ customObject
The custom object used to update the referenced object.
■ bFlush
A boolean that specifies if the changes must be flushed immediately. If bFlush is
set to true, this method invocation flushes the changes immediately.
Exceptions
InvalidOperationException - The specified connection is not open or the custom
object does not map to the type of referenced object.
Remarks
This method marks the specified REF for update. Depending on whether the value of
bFlush is set to true or false, the following occurs:
■ True
The object referenced by the specified REF is updated immediately in the database.
Before flushing objects, it is required that the application has explicitly started a
transaction by executing the BeginTransaction method on the
OracleConnection object. This is because if the object being flushed has not
already been locked by the application, an exclusive lock is obtained implicitly for
the object. The lock is only released when the transaction commits or rollbacks.
■ False
The object referenced by the REF is not updated immediately in the database, but
only when a subsequent Flush method is invoked for the specified REF or the
FlushCache method is invoked for the specified connection.
The connection must be opened explicitly by the application. This method does not
open the connection implicitly.
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
OracleUdtFetchOption Enumeration
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
OracleUdtStatus Enumeration
See Also:
■ "Oracle.DataAccess.Types Namespace" on page 1-9
■ OracleRef Class
■ OracleRef Members
This chapter describes Oracle Data Provider for .NET support for Bulk Copy
operations.
Note: Oracle Data Provider for .NET bulk copy operations do not
support loading of UDT type columns.
OracleBulkCopy Class
An OracleBulkCopy object efficiently bulk loads or copies data into an Oracle table
from another data source.
Class Inheritance
System.Object
System.OracleBulkCopy
Declaration
// C#
public sealed class OracleBulkCopy : IDisposable
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
The OracleBulkCopy class can be used to write data to Oracle database tables only.
However, the data source is not limited to Oracle databases; any data source can be
used, as long as the data can be loaded to a DataTable instance or read with an
IDataReader instance.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Members
■ OracleBulkCopy Constructors
■ OracleBulkCopy Properties
■ OracleBulkCopy Public Methods
■ OracleBulkCopy Events
OracleBulkCopy Members
OracleBulkCopy Constructors
OracleBulkCopy constructors are listed in Table 17–1.
OracleBulkCopy Properties
OracleBulkCopy properties are listed in Table 17–2.
OracleBulkCopy Events
OracleBulkCopy events are listed in Table 17–4.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
OracleBulkCopy Constructors
Overload List:
■ OracleBulkCopy(OracleConnection)
This constructor instantiates a new instance of OracleBulkCopy class using the
specified connection and default value for OracleBulkCopyOptions.
■ OracleBulkCopy(string)
This constructor instantiates a new instance of OracleBulkCopy based on the
supplied connectionString and default value for OracleBulkCopyOptions.
■ OracleBulkCopy(OracleConnection, OracleBulkCopyOptions)
This constructor instantiates a new instance of OracleBulkCopy using the
specified connection object and OracleBulkCopyOptions value.
■ OracleBulkCopy(string, OracleBulkCopyOptions)
This constructor instantiates a new instance of OracleConnection based on the
supplied connectionString and OracleBulkCopyOptions value.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
OracleBulkCopy(OracleConnection)
This constructor instantiates a new instance of OracleBulkCopy class using the
specified connection and default OracleBulkCopyOptions enumeration values.
Declaration
// C#
public OracleBulkCopy(OracleConnection connection);
Parameters
■ connection
The open instance of OracleConnection that performs the bulk copy operation.
Exceptions
ArgumentNullException - The connection parameter is null.
InvalidOperationException - The connection is not in the open state.
Remarks
The connection object passed to this constructor must be open. It remains open after
the OracleBulkCopy instance is closed.
This constructor uses the default enumeration value
OracleBulkCopyOptions.Default.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
■ "OracleBulkCopyOptions Enumeration" on page 17-42
OracleBulkCopy(string)
This constructor instantiates a new instance of the OracleBulkCopy class by first
creating an OracleConnection object based on the supplied connectionString ,
then initializing the new OracleBulkCopy object with the OracleConnection
object and OracleBulkCopyOptions default value.
Declaration
// C#
public OracleBulkCopy(string connectionString);
Parameters
■ connectionString
The connection information used to connect to the Oracle database and perform
the bulk copy operation.
Exception
ArgumentNullException - The connectionString parameter is null.
ArgumentException - The connectionString parameter is empty.
Remarks
The WriteToServer method opens the connection, if it is not already opened. The
connection is automatically closed when the OracleBulkCopy instance is closed.
This constructor uses the default enumeration value
OracleBulkCopyOptions.Default.
The Connection property is set to the OracleConnection object initialized using
the supplied connectionString.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
■ "OracleBulkCopyOptions Enumeration" on page 17-42
OracleBulkCopy(OracleConnection, OracleBulkCopyOptions)
This constructor instantiates a new instance of OracleBulkCopy using the specified
connection object and OracleBulkCopyOptions value.
Declaration
// C#
public OracleBulkCopy(OracleConnection connection, OracleBulkCopyOptions
copyOptions);
Parameters
■ connection
The open instance of an OracleConnection object that performs the bulk copy
operation.
■ copyOptions
The combination of OracleBulkCopyOptions enumeration values that
determine the behavior of the OracleBulkCopy object.
Exceptions
ArgumentNullException - The connection parameter is null.
InvalidOperationException - The connection is not in the open state.
Remarks
The connection passed to this constructor must be open. It remains open after the
OracleBulkCopy instance is closed.
The Connection property is set to the supplied connection.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
■ "OracleBulkCopyOptions Enumeration" on page 17-42
OracleBulkCopy(string, OracleBulkCopyOptions)
This constructor instantiates a new instance of the OracleBulkCopy class by first
creating an OracleConnection object based on the supplied connectionString,
then initializing the new OracleBulkCopy object with the OracleConnection
object and the supplied OracleBulkCopyOptions enumeration values.
Declaration
// C#
public OracleBulkCopy(string connectionString, OracleBulkCopyOptions copyOptions);
Parameters
■ connectionString
The connection information used to connect to the Oracle database to perform the
bulk copy operation.
■ copyOptions
The combination of OracleBulkCopyOptions enumeration values that
determine the behavior of the bulk copy operation.
Exceptions
ArgumentNullException - The connectionString is null.
ArgumentException - The connectionString parameter is empty.
Remarks
The constructor uses the new instance of the OracleConnection class to initialize a
new instance of the OracleBulkCopy class. The OracleBulkCopy instance behaves
according to options supplied in the copyOptions parameter.
The connection is automatically closed when the OracleBulkCopy instance is closed.
The Connection property is set to an OracleConnection object initialized using
the supplied connectionString.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
■ "OracleBulkCopyOptions Enumeration" on page 17-42
OracleBulkCopy Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
BatchSize
This property specifies the number of rows to be sent as a batch to the database.
Declaration
// C#
public int BatchSize {get; set;}
Property Value
An integer value for the number of rows to be sent to the database as a batch.
Exceptions
ArgumentOutOfRangeException - The batch size is less than zero.
Remarks
The default value is zero, indicating that the rows are not sent to the database in
batches. The entire set of rows are sent in one single batch.
A batch is complete when BatchSize number of rows have been processed or there
are no more rows to send to the database.
■ If BatchSize > 0 and the UseInternalTransaction bulk copy option is
specified, each batch of the bulk copy operation occurs within a transaction. If the
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
■ "OracleBulkCopyOptions Enumeration" on page 17-42
BulkCopyOptions
This property specifies the OracleBulkCopyOptions enumeration value that
determines the behavior of the bulk copy option.
Declaration
// C#
public OracleBulkCopyOptions BulkCopyOptions {get; set;}
Property Value
The OracleBulkCopyOptions enumeration object that defines the behavior of the
bulk copy operation.
Exceptions
ArgumentNullException - The bulk copy options set is null.
Remarks
The default value of this property is OracleBulkCopyOptions.Default value.
This property can be used to change the bulk copy options between the batches of a
bulk copy operation.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
■ "OracleBulkCopyOptions Enumeration" on page 17-42
BulkCopyTimeout
This property specifies the number of seconds allowed for the bulk copy operation to
complete before it is aborted.
Declaration
// C#
public int BulkCopyTimeout {get; set;}
Property Value
An integer value for the number of seconds after which the bulk copy operation times
out.
Exceptions
ArgumentOutOfRangeException - The timeout value is set to less than zero.
Remarks
The default value is 30 seconds.
If BatchSize>0, rows that were sent to the database in the previous batches remain
committed. The rows that are processed in the current batch are not sent to the
database. If BatchSize=0, no rows are sent to the database.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
ColumnMappings
This property specifies the column mappings between the data source and destination
table.
Declaration
// C#
public OracleBulkCopyColumnMappingCollection ColumnMappings {get;}
Property Value
The OracleBulkCopyColumnMappingCollection object that defines the column
mapping between the source and destination table.
Remarks
The ColumnMappings collection is unnecessary if the data source and the destination
table have the same number of columns, and the ordinal position of each source
column matches the ordinal position of the corresponding destination column.
However, if the column counts differ, or the ordinal positions are not consistent, the
ColumnMappings collection must be used to ensure that data is copied into the
correct columns.
During the execution of a bulk copy operation, this collection can be accessed, but it
cannot be changed.
By default, this property specifies an empty collection of column mappings.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
Connection
This property specifies the OracleConnection object that the Oracle database uses
to perform the bulk copy operation.
Declaration
// C#
public OracleConnection Connection {get; }
Property Value
The OracleConnection object used for the bulk copy operations.
Remarks
This property gets the connection constructed by the OracleBulkCopy, if the
OracleBulkCopy object is initialized using a connection string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
DestinationTableName
This property specifies the database table that the data is loaded into.
Declaration
// C#
public string DestinationTableName {get; set;}
Property Value
A string value that identifies the destination table name.
Exceptions
ArgumentNullException - The destination table name set is null.
ArgumentException - The destination table name is empty.
Remarks
If DestinationTableName is modified while a WriteToServer operation is
running, the change does not affect the current operation. The new
DestinationTableName value is used the next time a WriteToServer method is
called.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
NotifyAfter
This property defines the number of rows to be processed before a notification event is
generated.
Declaration
// C#
public int NotifyAfter {get; set;}
Property Value
An integer value that specifies the number of rows to be processed before the
notification event is raised.
Exceptions
ArgumentOutOfRangeException - The property value is set to a number less than
zero.
Remarks
The default value for this property is zero, to specify that no notifications events are to
be generated.
This property can be retrieved in user interface components to display the progress of
a bulk copy operation. The NotifyAfter property can be set at anytime, even during
a bulk copy operation. The changes take effect for the next notification and any
subsequent operations on the same instance.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
Close
This method closes the OracleBulkCopy instance.
Declaration
// C#
public void Close();
Exceptions
InvalidOperationException - The Close method was called from a
OracleRowsCopied event.
Remarks
After the Close method is called on a OracleBulkCopy object, no other operation
can succeed. Calls to the WriteToServer method throw an
InvalidOperationException. The Close method closes the connection if the
connection was opened by the OracleBulkCopy object, that is, if the
OracleBulkCopy object was created by a constructor that takes a connection string.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
Dispose
This method releases any resources or memory allocated by the object.
Declaration
// C#
public void Dispose();
Implements
IDisposable
Remarks
After the Dispose method is called on the OracleBulkCopy object, no other
operation can succeed. The connection is closed if the connection was opened by the
OracleBulkCopy object, that is, if a constructor that takes a connection string created
the OracleBulkCopy object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
WriteToServer
WriteToServer copies rows to a destination table.
Overload List:
■ WriteToServer(DataRow[])
This method copies all rows from the supplied DataRow array to a destination
table specified by the DestinationTableName property of the
OracleBulkCopy object.
■ WriteToServer(DataTable)
This method copies all rows in the supplied DataTable to a destination table
specified by the DestinationTableName property of the OracleBulkCopy
object.
■ WriteToServer(IDataReader)
This method copies all rows in the supplied IDataReader to a destination table
specified by the DestinationTableName property of the OracleBulkCopy
object.
■ WriteToServer(DataTable, DataRowState)
This method copies rows that match the supplied row state in the supplied
DataTable to a destination table specified by the DestinationTableName
property of the OracleBulkCopy object.
■ WriteToServer(OracleRefCursor)
This method copies all rows from the specified OracleRefCursor to a
destination table specified by the DestinationTableName property of the
OracleBulkCopy object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
WriteToServer(DataRow[])
This method copies all rows from the supplied DataRow array to a destination table
specified by the DestinationTableName property of the OracleBulkCopy object.
Declaration
// C#
public void WriteToServer(DataRow[] rows);
Parameters
■ rows
An array of DataRow objects to be copied to the destination table.
Exceptions
ArgumentNullException - The rows parameter is null.
InvalidOperationException - The connection is not in an open state.
Remarks
The ColumnMappings collection maps from the DataRow columns to the destination
database table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
WriteToServer(DataTable)
This method copies all rows in the supplied DataTable to a destination table
specified by the DestinationTableName property of the OracleBulkCopy object.
Declaration
// C#
public void WriteToServer(DataTable table);
Parameters
■ table
The source DataTable containing rows to be copied to the destination table.
Exceptions
ArgumentNullException - The table parameter is null.
InvalidOperationException - The connection is not in an open state.
Remarks
All rows in the DataTable are copied to the destination table except those that have
been deleted.
The ColumnMappings collection maps from the DataTable columns to the
destination database table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
WriteToServer(IDataReader)
This method copies all rows in the supplied IDataReader to a destination table
specified by the DestinationTableName property of the OracleBulkCopy object.
Declaration
// C#
public void WriteToServer(IDataReader reader);
Parameters
■ reader
A IDataReader instance containing rows to be copied to the destination table.
Exceptions
ArgumentNullException - The reader parameter is null.
InvalidOperationException - The connection is not in an open state.
Remarks
The bulk copy operation starts with the next available row of the data reader.
Typically, the reader returned by a call to the ExecuteReader method is passed to
the WriteToServer method so that the next row becomes the first row. To copy
multiple result sets, the application must call NextResult on the reader and then
call the WriteToServer method again.
This WriteToServer method changes the state of the reader as it calls reader.Read
internally to get the source rows. Thus, at the end of the WriteToServer operation,
the reader is at the end of the result set.
The ColumnMappings collection maps from the data reader columns to the
destination database table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
WriteToServer(DataTable, DataRowState)
This method copies rows that match the supplied row state in the supplied
DataTable to a destination table specified by the DestinationTableName
property of the OracleBulkCopy object.
Declaration
// C#
public void WriteToServer(DataTable table, DataRowState rowState);
Parameters
■ table
A DataTable containing rows to be copied to the destination table.
■ rowState
The DataRowState enumeration value. Only rows matching the row state are
copied to the destination.
Exceptions
ArgumentNullException - The table or rowState parameter is null.
InvalidOperationException - The connection is not in an open state.
Remarks
Only rows in the DataTable that are in the state indicated in the rowState
argument and have not been deleted are copied to the destination table.
The ColumnMappings collection maps from the DataTable columns to the
destination database table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
WriteToServer(OracleRefCursor)
This method copies all rows from the specified OracleRefCursor to a destination
table specified by the DestinationTableName property of the OracleBulkCopy
object.
Declaration
// C#
public void WriteToServer(OracleRefCursor refCursor);
Parameters
■ refCursor
An OracleRefCursor object containing rows to be copied to the destination
table.
Exceptions
ArgumentNullException - The refCursor parameter is null
InvalidOperationException - The connection is not in an open state.
Remarks
The ColumnMappings collection maps from the OracleRefCursor columns to the
destination database table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
OracleBulkCopy Events
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
OracleRowsCopied
This event is triggered every time the number of rows specified by the
OracleBulkCopy.NotifyAfter property has been processed.
Declaration
// C#
public event OracleRowsCopiedEventHandler OracleRowsCopied;
Exceptions
InvalidOperationException - The Close method is called inside this event.
Remarks
This event is raised when the number of rows specified by the NotifyAfter property
has been processed. It does not imply that the rows have been sent to the database or
committed.
To cancel the operation from this event, use the Abort property of
OracleRowsCopiedEventArgs class.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy Class
■ OracleBulkCopy Members
■ "NotifyAfter" on page 17-13
OracleBulkCopyColumnMapping Class
Class Inheritance
System.Object
System.OracleBulkCopyColumnMapping
Declaration
// C#
public sealed class OracleBulkCopyColumnMapping
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
Column mappings define the mapping between data source and the target table.
It is not necessary to specify column mappings for all the columns in the data source. If
a ColumnMapping is not specified, then, by default, columns are mapped based on
the ordinal position. This succeeds only if the source and destination table schema
match. If there is a mismatch, an InvalidOperationException is thrown.
All the mappings in a mapping collection must be by name or ordinal position.
Note: Oracle Data Provider for .NET makes one or more round-trips
to the database to determine the column name if the mapping is
specified by ordinal position. To avoid this performance overhead,
specify the mapping by column name.
Example
// C#
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Members
■ OracleBulkCopyColumnMapping Constructors
■ OracleBulkCopyColumnMapping Properties
OracleBulkCopyColumnMapping Members
OracleBulkCopyColumnMapping Constructors
The OracleBulkCopyColumnMapping constructors are listed in Table 17–8.
OracleBulkCopyColumnMapping Properties
The OracleBulkCopyColumnMapping properties are listed in Table 17–9.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
OracleBulkCopyColumnMapping Constructors
Overload List:
■ OracleBulkCopyColumnMapping()
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class
■ OracleBulkCopyColumnMapping(int, int)
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class using the provided source column
ordinal and destination column ordinal.
■ OracleBulkCopyColumnMapping(int, string)
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class using the provided source column
ordinal and destination column name.
■ OracleBulkCopyColumnMapping(string, int)
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class using the provided source column
name and destination column ordinal.
■ OracleBulkCopyColumnMapping(string, string)
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class using the provided source column
name and destination column name.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
OracleBulkCopyColumnMapping()
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class.
Declaration
// C#
public OracleBulkCopyColumnMapping();
Remarks
Applications that use this constructor must define the source for the mapping using
the SourceColumn or SourceOrdinal property, and must define the destination for
the mapping using the DestinationColumn or DestinationOrdinal property.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
OracleBulkCopyColumnMapping(int, int)
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class using the provided source and destination
column ordinal positions.
Declaration
// C#
public OracleBulkCopyColumnMapping(int sourceColumnOrdinal,
int destinationOrdinal);
Parameters
■ sourceColumnOrdinal
The ordinal position of the source column within the data source.
■ destinationOrdinal
The ordinal position of the destination column within the destination table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
OracleBulkCopyColumnMapping(int, string)
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class using the provided source column ordinal
and destination column name.
Declaration
// C#
public OracleBulkCopyColumnMapping(int sourceColumnOrdinal,
string destinationColumn);
Parameters
■ sourceColumnOrdinal
The ordinal position of the source column within the data source.
■ destinationColumn
The name of the destination column within the destination table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
OracleBulkCopyColumnMapping(string, int)
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class using the provided source column name
and destination column ordinal.
Declaration
// C#
public OracleBulkCopyColumnMapping(string sourceColumn, int destinationOrdinal);
Parameters
■ sourceColumn
The name of the source column within the data source.
■ destinationOrdinal
The ordinal position of the destination column within the destination table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
OracleBulkCopyColumnMapping(string, string)
This constructor instantiates a new instance of the
OracleBulkCopyColumnMapping class using the provided source and destination
column names.
Declaration
// C#
public OracleBulkCopyColumnMapping(string sourceColumn, string destinationColumn);
Parameters
■ sourceColumn
The name of the source column within the data source.
■ destinationColumn
The name of the destination column within the destination table.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
OracleBulkCopyColumnMapping Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
DestinationColumn
This property specifies the column name of the destination table that is being mapped.
Declaration
// C#
public string DestinationColumn {get; set;}
Property Value
A string value that represents the destination column name of the mapping.
Remarks
The DestinationColumn and DestinationOrdinal properties are mutually
exclusive. The last value set takes precedence.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
DestinationOrdinal
This property specifies the column ordinal value of the destination table that is being
mapped.
Declaration
// C#
public int DestinationOrdinal {get; set;}
Property Value
An integer value that represents the destination column ordinal of the mapping.
Exceptions
IndexOutOfRangeException - The destination ordinal is invalid.
Remarks
The DestinationOrdinal and DestinationColumn properties are mutually
exclusive. The last value set takes precedence.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
SourceColumn
This property specifies the column name of the data source that is being mapped.
Declaration
// C#
public string SourceColumn {get; set;}
Property Value
A string value that represents the source column name of the mapping.
Remarks
The SourceColumn and SourceOrdinal properties are mutually exclusive. The last
value set takes precedence.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
SourceOrdinal
This property specifies the column ordinal value of the data source that is being
mapped.
Declaration
// C#
public int SourceOrdinal {get; set;}
Property Value
An integer value that represents the source column ordinal of the mapping.
Exceptions
IndexOutOfRangeException - The source ordinal is invalid.
Remarks
The SourceOrdinal and SourceColumn properties are mutually exclusive. The last
value set takes precedence.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMapping Class
■ OracleBulkCopyColumnMapping Members
OracleBulkCopyColumnMappingCollection Class
Class Inheritance
System.Object
System.CollectionBase
System.OracleBulkCopyColumnMappingCollection
Declaration
// C#
public sealed class OracleBulkCopyColumnMappingCollection : CollectionBase
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
Column mappings define the mapping between data source and the target table.
It is not necessary to specify column mappings for all the columns in the data source. If
a ColumnMapping is not specified, then, by default, columns are mapped based on
the ordinal position. This succeeds only if the source and destination table schema
match. If there is a mismatch, an InvalidOperationException is thrown.
All the mappings in a mapping collection must be by name or ordinal position.
Note: Oracle Data Provider for .NET makes one or more round-trips
to the database to determine the column name if the mapping is
specified by ordinal position. To avoid this performance overhead,
specify the mapping by column name.
Example
// C#
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
■ OracleBulkCopyColumnMappingCollection Properties
■ OracleBulkCopyColumnMappingCollection Public Methods
OracleBulkCopyColumnMappingCollection Members
OracleBulkCopyColumnMappingCollection Properties
The OracleBulkCopyColumnMappingCollection properties are listed in
Table 17–11.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
OracleBulkCopyColumnMappingCollection Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Item[index]
This property gets or sets the OracleBulkCopyColumnMapping object at the
specified index.
Declaration
// C#
public OracleBulkCopyColumnMapping this[int index] {get;set;}
Parameters
■ index
The zero-based index of the OracleBulkCopyColumnMapping being set or
retrieved.
Property Value
An OracleBulkCopyColumnMapping object at the specified index.
Exceptions
IndexOutOfRangeException - The specified index does not exist.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Add
Add methods add objects to the collection.
Overload List:
■ Add(OracleBulkCopyColumnMapping)
This method adds the supplied OracleBulkCopyColumnMapping object to the
collection.
■ Add(int, int)
This method creates and adds an OracleBulkCopyColumnMapping object to the
collection using the supplied source and destination column ordinal positions.
■ Add(int, string)
This method creates and adds an OracleBulkCopyColumnMapping object to the
collection using the supplied source column ordinal and destination column name.
■ Add(string, int)
This method creates and adds an OracleBulkCopyColumnMapping object to the
collection using the supplied source column name and destination column ordinal.
■ Add(string, string)
This method creates and adds an OracleBulkCopyColumnMapping object to the
collection using the supplied source and destination column names.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Add(OracleBulkCopyColumnMapping)
This method adds the supplied OracleBulkCopyColumnMapping object to the
collection.
Declaration
// C#
public OracleBulkCopyColumnMapping Add(OracleBulkCopyColumnMapping
bulkCopyColumnMapping);
Parameters
■ bulkCopyColumnMapping
The OracleBulkCopyColumnMapping object that describes the mapping to be
added to the collection.
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Add(int, int)
This method creates and adds an OracleBulkCopyColumnMapping object to the
collection using the supplied source and destination column ordinal positions.
Declaration
// C#
public OracleBulkCopyColumnMapping Add(int sourceColumnIndex,
int destinationColumnIndex);
Parameters
■ sourceColumnIndex
The ordinal position of the source column within the data source.
■ destinationColumnIndex
The ordinal position of the destination column within the destination table.
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
Return Value
The newly created OracleBulkCopyColumnMapping object that was added to the
collection.
Remarks
It is not necessary to specify column mappings for all the columns in the data source. If
a ColumnMapping is not specified, then, by default, columns are mapped based on
the ordinal position. This succeeds only if the source and destination table schema
match. If there is a mismatch, an InvalidOperationException is thrown.
All the mappings in a mapping collection must be by name or ordinal position.
Note: Oracle Data Provider for .NET makes one or more round-trips
to the database to determine the column name if the mapping is
specified by ordinal position. To avoid this performance overhead,
specify the mapping by column name.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Add(int, string)
This method creates and adds an OracleBulkCopyColumnMapping object to the
collection using the supplied source column ordinal and destination column name.
Declaration
// C#
public OracleBulkCopyColumnMapping Add(int sourceColumnIndex,
string destinationColumn);
Parameters
■ sourceColumnIndex
The ordinal position of the source column within the data source.
■ destinationColumn
The name of the destination column within the destination table.
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
Return Value
The newly created OracleBulkCopyColumnMapping object that was added to the
collection.
Remarks
It is not necessary to specify column mappings for all the columns in the data source. If
a ColumnMapping is not specified, then, by default, columns are mapped based on
the ordinal position. This succeeds only if the source and destination table schema
match. If there is a mismatch, an InvalidOperationException is thrown.
All the mappings in a mapping collection must be by name or ordinal position.
Note: Oracle Data Provider for .NET makes one or more round trips
to the database to determine the column names if the mapping is
specified by ordinal resulting in a performance overhead. Therefore, it
is recommended to specify the mapping by column names.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Add(string, int)
This method creates and adds an OracleBulkCopyColumnMapping object to the
collection using the supplied source column name and destination column ordinal.
Declaration
// C#
public OracleBulkCopyColumnMapping Add(string sourceColumn,
int destinationColumnIndex);
Parameters
■ sourceColumn
The name of the source column within the data source.
■ destinationColumnIndex
The ordinal position of the destination column within the destination table.
Return Value
The newly created OracleBulkCopyColumnMapping object that was added to the
collection.
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
Remarks
It is not necessary to specify column mappings for all the columns in the data source. If
a ColumnMapping is not specified, then, by default, columns are mapped based on
the ordinal position. This succeeds only if the source and destination table schema
match. If there is a mismatch, an InvalidOperationException is thrown.
All the mappings in a mapping collection must be by name or ordinal position.
Note: Oracle Data Provider for .NET makes one or more round trips
to the database to determine the column names if the mapping is
specified by ordinal resulting in a performance overhead. Therefore, it
is recommended to specify the mapping by column names.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Add(string, string)
This method creates and adds an OracleBulkCopyColumnMapping object to the
collection using the supplied source and destination column names.
Declaration
// C#
public OracleBulkCopyColumnMapping Add(string sourceColumn,
string destinationColumn);
Parameters
■ sourceColumn
The name of the source column within the data source.
■ destinationColumn
The name of the destination column within the destination table.
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
Return Value
The newly created OracleBulkCopyColumnMapping object that was added to the
collection.
Remarks
It is not necessary to specify column mappings for all the columns in the data source. If
a ColumnMapping is not specified, then, by default, columns are mapped based on
the ordinal position. This succeeds only if the source and destination table schema
match. If there is a mismatch, an InvalidOperationException is thrown.
All the mappings in a mapping collection must be by name or ordinal position.
Note: Oracle Data Provider for .NET makes one or more round-trips
to the database to determine the column name if the mapping is
specified by ordinal position. To avoid this performance overhead,
specify the mapping by column name.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Clear
This method clears the contents of the collection.
Declaration
// C#
public void Clear();
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
Remarks
The Clear method is most commonly used when an application uses a single
OracleBulkCopy instance to process more than one bulk copy operation. If column
mappings are created for one bulk copy operation, the
OracleBulkCopyColumnMappingCollection must be cleared after the
WriteToServer method invocation and before the next bulk copy is processed.
It is usually more efficient to perform several bulk copies using the same
OracleBulkCopy instance than to use a separate OracleBulkCopy for each
operation.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Contains
This method returns a value indicating whether or not a specified
OracleBulkCopyColumnMapping object exists in the collection.
Declaration
// C#
public bool Contains(OracleBulkCopyColumnMapping value);
Parameters
■ value
A valid OracleBulkCopyColumnMapping object.
Return Value
Returns true if the specified mapping exists in the collection; otherwise, returns
false.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
CopyTo
This method copies the elements of the
OracleBulkCopyColumnMappingCollection to an array of
OracleBulkCopyColumnMapping items, starting at a specified index.
Declaration
// C#
public void CopyTo(OracleBulkCopyColumnMapping[] array, int index);
Parameters
■ array
The one-dimensional OracleBulkCopyColumnMapping array that is the
destination for the elements copied from the
OracleBulkCopyColumnMappingCollection object. The array must have
zero-based indexing.
■ index
The zero-based array index at which copying begins.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
IndexOf
This method returns the index of the specified OracleBulkCopyColumnMapping
object.
Declaration
// C#
public int IndexOf(OracleBulkCopyColumnMapping value);
Parameters
■ value
The OracleBulkCopyColumnMapping object that is being returned.
Return Value
The zero-based index of the column mapping or -1 if the column mapping is not found
in the collection.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Insert
This method inserts a new OracleBulkCopyColumnMapping object in the
collection, at the index specified.
Declaration
// C#
public void Insert(int index, OracleBulkCopyColumnMapping value);
Parameters
■ index
The integer value of the location within the
OracleBulkCopyColumnMappingCollection at which the new
OracleBulkCopyColumnMapping is inserted.
■ value
The OracleBulkCopyColumnMapping object to be inserted in the collection.
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
Remove
This method removes the specified OracleBulkCopyColumnMapping element from
the OracleBulkCopyColumnMappingCollection.
Declaration
// C#
public void Remove(OracleBulkCopyColumnMapping value);
Parameters
■ value
The OracleBulkCopyColumnMapping object to be removed from the collection.
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
Remarks
The Remove method is most commonly used when a single OracleBulkCopy
instance processes more than one bulk copy operation. If column mappings are created
for one bulk copy operation, mappings that no longer apply must be removed after the
WriteToServer method invocation and before mappings are defined for the next
bulk copy. The Clear method can clear the entire collection, and the Remove and the
RemoveAt methods can remove mappings individually.
It is usually more efficient to perform several bulk copies using the same
OracleBulkCopy instance than to use a separate OracleBulkCopy for each
operation.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
RemoveAt
This method removes the mapping from the collection at the specified index.
Declaration
// C#
public void RemoveAt(int index);
Parameters
■ index
The zero-based index of the OracleBulkCopyColumnMapping object to be
removed from the collection.
Exceptions
InvalidOperationException - The bulk copy operation is in progress.
Remarks
The RemoveAt method is most commonly used when a single OracleBulkCopy
instance is used to process more than one bulk copy operation. If column mappings
are created for one bulk copy operation, mappings that no longer apply must be
removed after the WriteToServer method invocation and before the mappings for
the next bulk copy are defined. The Clear method can clear the entire collection, and
the Remove and the RemoveAt methods can remove mappings individually.
It is usually more efficient to perform several bulk copies using the same
OracleBulkCopy instance than to use a separate OracleBulkCopy for each
operation.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopyColumnMappingCollection Class
■ OracleBulkCopyColumnMappingCollection Members
OracleBulkCopyOptions Enumeration
UseInternalTransaction Indicates that each batch of the bulk copy operation occurs
within a transaction. If the connection used to perform the
bulk copy operation is already part of a transaction, an
InvalidOperationException exception is raised.
If this member is not specified, BatchSize number of rows
are sent to the database, without any transaction-related
activity.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleBulkCopy "BulkCopyOptions" on page 17-10
OracleRowsCopiedEventHandler Delegate
Declaration
// C#
public delegate void OracleRowsCopiedEventHandler (object sender,
OracleRowsCopiedEventArgs eventArgs);
Parameters
■ sender
The source of the event.
■ eventArgs
The OracleRowsCopiedEventArgs object that contains the event data.
Remarks
Event callbacks can be registered through this event delegate for applications that wish
to be notified every time the number of rows specified by the
OracleBulkCopy.NotifyAfter property has been processed.
If the event handler calls the OracleBulkCopy.Close method, an exception is
generated, and the OracleBulkCopy object state does not change.
The event handler can also set the OracleRowsCopiedEventArgs.Abort property
to true to indicate that the bulk copy operation must be aborted. If the bulk copy
operation is part of an external transaction, an exception is generated and the
transaction is not rolled back. The application is responsible for either committing or
rolling back the external transaction.
If there is no external transaction, the internal transaction for the current batch of rows
is automatically rolled back. However the previous batches of imported rows are
unaffected, as their transactions have already been committed.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 2.0 or later
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ "OracleRowsCopied" on page 20
■ "NotifyAfter" on page 17-13
OracleRowsCopiedEventArgs Class
Class Inheritance
System.Object
System.EventArgs
System.OracleRowsCopiedEventArgs
Declaration
// C#
public class OracleRowsCopiedEventArgs : EventArgs
Thread Safety
All public static methods are thread-safe, although instance methods do not guarantee
thread safety.
Remarks
Each time the number of rows represented by the OracleBulkCopy.NotifyAfter
property is processed, the OracleBulkCopy.OracleRowsCopied event is raised,
providing an OracleRowsCopiedEventArgs object that stores the event data.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowsCopiedEventArgs Members
■ OracleRowsCopiedEventArgs Constructors
■ OracleRowsCopiedEventArgs Properties
OracleRowsCopiedEventArgs Members
OracleRowsCopiedEventArgs Constructors
OracleRowsCopiedEventArgs constructors are listed in Table 17–16.
OracleRowsCopiedEventArgs Properties
OracleRowsCopiedEventArgs properties are listed in Table 17–17.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowsCopiedEventArgs Class
OracleRowsCopiedEventArgs Constructors
Overload List:
■ OracleRowsCopiedEventArgs(long)
This constructor creates a new instance of the OracleRowsCopiedEventArgs
object.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowsCopiedEventArgs Class
■ OracleRowsCopiedEventArgs Members
OracleRowsCopiedEventArgs(long)
This constructor creates a new instance of the OracleRowsCopiedEventArgs object.
Declaration
// C#
public OracleRowsCopiedEventArgs(long rowsCopied);
Parameters
■ rowsCopied
An Int64 value that indicates the number of rows copied during the current bulk
copy operation.
Remarks
The value in the rowsCopied parameter is reset by each call to a WriteToServer
method.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowsCopiedEventArgs Class
■ OracleRowsCopiedEventArgs Members
OracleRowsCopiedEventArgs Properties
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowsCopiedEventArgs Class
■ OracleRowsCopiedEventArgs Members
Abort
This property retrieves or sets a value that indicates whether or not the bulk copy
operation is aborted.
Declaration
// C#
public bool Abort{get; set;}
Property Value
Returns true if the bulk copy operation is to be aborted; otherwise, returns false.
Remarks
Set the Abort property to true to cancel the bulk copy operation.
If the Close method is called from OracleRowsCopied, an exception is generated,
and the OracleBulkCopy object state does not change.
If the application does not create a transaction, the internal transaction corresponding
to the current batch is automatically rolled back. However, changes related to previous
batches within the bulk copy operation are retained, because the transactions in those
batches are committed. This case is applicable only when
UseInternalTransaction bulk copy option is chosen.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowsCopiedEventArgs Class
■ OracleRowsCopiedEventArgs Members
RowsCopied
This property retrieves a value that represents the number of rows copied during the
current bulk copy operation.
Declaration
// C#
public long RowsCopied {get;}
Property Value
An Int64 value that returns the number of rows copied.
Remarks
The value in the RowsCopied property is reset by each call to a WriteToServer
method.
See Also:
■ "Oracle.DataAccess.Client Namespace" on page 1-3
■ OracleRowsCopiedEventArgs Class
■ OracleRowsCopiedEventArgs Members
See Also:
■ "Support for Schema Discovery" on page 3-21
■ "GetSchema" on page 5-99
■ MetaDataCollections
■ DataSourceInformation
■ DataTypes
■ Restrictions
■ ReservedWords
MetaDataCollections
Table A–1 is a list of metadata collections that is available from the data source, such as
tables, columns, indexes, and stored procedures.
DataSourceInformation
Table A–2 lists DataSourceInformation information which may include these
columns and possibly others.
DataTypes
Table A–3 lists DataTypes Collection information which may include these columns
and possibly others.
Restrictions
Table A–4 lists Restrictions, including the following columns.
ReservedWords
The ReservedWords collection exposes information about the words that are
reserved by the database currently connected to ODP.NET.
Table A–5 lists the ReservedWords Collection.
Tables
Table A–6 lists the column name, data type, and description of the Tables Schema
Schema Collection.
Columns
Table A–7 lists the column name, data type, and description of the Columns Schema
Collection .
Views
Table A–8 lists the column name, data type, and description of the Views Schema
Collection.
XMLSchema
Table A–9 lists the column name, data type and description of the XMLSchema
Schema Collection.
Note: This collection is only available with Oracle Database 10g and
later.
Users
Table A–10 lists the column name, data type and description of the Users Schema
Collection.
Synonyms
Table A–11 lists the column name, data type and description of the Synonyms Schema
Collection.
Sequences
Table A–12 lists the column name, data type, and description of the Sequences Schema
Collection.
Functions
Table A–13 lists the column name, data type, and description of the Functions Schema
Collection.
Procedures
Table A–14 lists the column name, data type, and description of the Procedures
Schema Collection.
ProcedureParameters
Table A–15 lists the column name, data type and description of the
ProcedureParameters Schema Collection.
Arguments
Table A–16 lists the column name, data type, and description of the Arguments
Schema Collection.
Packages
Table A–17 lists the column name, data type, and description of the Packages Schema
Collection.
PackageBodies
Table A–18 lists the column name, data type, and description of the PackageBodies
Schema Collection.
JavaClasses
Table A–19 lists the column name, data type, and description of the JavaClasses
Schema Collection.
Indexes
Table A–20 lists the column name, data type, and description of the Indexes Schema
Collection.
IndexColumns
Table A–21 lists the column name, data type, and description of the IndexColumns
Schema Collection.
PrimaryKeys
Table A–22 lists the column name, data type, and description of the PrimaryKeys
Schema Collection.
ForeignKeys
Table A–23 lists the column name, data type, and description of the ForeignKeys
Schema Collection.
ForeignKeyColumns
Table A–24 lists the column name, data type, and description of the
ForeignKeyColumns Schema Collection.
UniqueKeys
Table A–25 lists the column name, data type, and description of the UniqueKeys
Schema Collection.
assembly
Assembly is Microsoft's term for the module that is created when a DLL or .EXE is
complied by a .NET compiler.
BFILES
External binary files that exist outside the database tablespaces residing in the
operating system. BFILES are referenced from the database semantics, and are also
known as external LOBs.
data provider
As the term is used with Oracle Data Provider for .NET, a data provider is the
connected component in the ADO.NET model and transfers data between a data
source and the DataSet.
DataSet
A DataSet is an in-memory copy of database data. The DataSet exists in memory
without an active connection to the database.
dirty writes
Dirty writes means writing uncommitted or dirty data.
DDL
DDL refers to data definition language, which includes statements defining or
changing data structure.
DOM
Document Object Model (DOM) is an application program interface (API) for
HTML and XML documents. It defines the logical structure of documents and
the way that a document is accessed and manipulated.
Glossary-1
Extensible Stylesheet Language Transformation (XSLT)
flush
Flush or flushing refers to recording changes (that is, sending modified data) to the
database.
goodness
The degree of load in the Oracle database. The lighter load is better and vice versa.
instantiate
A term used in object-based languages such as C# to refer to the creation of an object of
a specific class.
invalidation message
The content of a change notification which indicates that the cache is now invalid
namespace
■ .NET:
A namespace is naming device for grouping related types. More than one
namespace can be contained in an assembly.
■ XML Documents:
A namespace describes a set of related element names or attributes within an XML
document.
Glossary-2
URL
OracleDataReader
An OracleDataReader is a read-only, forward-only result set.
Oracle XML DB
Oracle XML DB is the name for a distinct group of technologies related to
high-performance XML storage and retrieval that are available within the Oracle
database. Oracle XML DB is not a separate server.
Oracle XML DB is based on the W3C XML data model.
PL/SQL
The Oracle procedural language extension to SQL.
primary key
The column or set of columns included in the definition of a table's PRIMARY KEY
constraint.
reference semantics
Reference semantics indicates that assignment is to a reference (an address such as a
pointer) rather than to a value. See value semantics.
REF
A data type that encapsulates references to row objects of a specified object type.
result set
The output of a SQL query, consisting of one or more rows of data.
savepoint
A point in the workspace to which operations can be rolled back.
stored procedure
A stored procedure is a PL/SQL block that Oracle stores in the database and can be
executed from an application.
Unicode
Unicode is a universal encoded character set that enables information from any
language to be stored using a single character set.
URL
URL (Universal Resource Locator).
Glossary-3
value semantics
value semantics
Value semantics indicates that assignment copies the value, not the reference or
address (such as a pointer). See reference semantics.
XPath
XML Path Language (XPath), based on a W3C recommendation, is a language for
addressing parts of an XML document. It is designed to be used by both XSLT and
XPointer. It can be used as a searching or query language as well as in hypertext
linking.
Glossary-4
Index
A BINARY_DOUBLE, 3-31
BINARY_FLOAT, 3-31
abstract data types, 3-77
binding, 3-31
ADO, 1-3
PL/SQL Associative Array, 3-36
ADO.NET, 1-3, 3-90
BLOB, 3-61
ADO.NET 1.x, 2-1
bulk copy constraints, 3-28
ADO.NET 2.0, 2-2, 3-18
bulk copy feature, 3-28
base or DbCommon classes, 3-19
restrictions, 3-28
classes and class members, 3-27
DbCommon classes, 3-18
ADO.NET 2.x, 2-1 C
ADTs, 3-77 C#, Visual Basic .NET, C++ .NET, 1-1
Advanced Queuing support, xxii caching ODP.NET parameter contexts, xxiv
app.config callback support, 3-16
sample, 3-122 case-sensitivity
setting performance counters, 3-8 column name mapping, 3-75
app.config file, 3-20 change notification
AppDomain, 3-8 ODP.NET support, 3-100
application config, 3-114 change notification, Database Change
AQ support, xxii Notification, 9-1
array bind characters with special meaning
OracleParameter, 3-40 in column data, 3-74
array bind operations, 3-39 in table or view, 3-75
ArrayBindCount, 5-13 characters with special meaning in XML, 3-68
ArrayBindIndex, 5-218 client applications, 1-1
ArrayBindSize, 5-263 client globalization settings, 3-111, 3-113
ArrayBindStatus, 5-264 client identifier, 3-16
error handling, 3-40 CLOB, 3-61
array binding, 3-39 close calls, 2-5
ArrayBindCount property, 5-13 CLR, 1-2
ArrayBindIndex property, 5-218 collection types, 3-78
ArrayBindSize property, 3-36, 3-40, 5-263 CollectionType property, 3-36
ArrayBindStatus property, 3-36, 3-40, 5-264 column data
ASP.NET, 1-2 special characters in, 3-74
assembly, 1-3 CommandBehavior.SequentialAccess, 3-51
ODP.NET, 1-3 commit transactions
changes to XML data, 3-77
B CommittableTransaction, 3-22
config files
batch processing, 3-27
samples, 3-122
support, 3-18
configuration settings
BatchUpdate
UDTs, 3-91
Microsoft Hotfix, 3-27
connect descriptor, 3-4
behavior of ExecuteScalar method for REF
connection dependency, 3-66
CURSOR, 3-59
connection optimization, 3-9
BFILE, 3-61
connection pool
Index-1
performance counters, 3-7 changes to, 3-73
connection pooling, 3-5 Database Change Notification
example, 3-5 best practices, 3-104
for Oracle RAC database, 3-9 performance considerations, 3-104
management, 3-7 database change notification, 2-4, 3-97, 3-99
Connection property, 3-62 ODP.NET support, 3-100
connection string builder, 3-18 database notification
ConnectionString attributes, 3-5 port to listen, 2-4
Connection Lifetime, 3-2, 3-5, 3-6 database shutdown, xxiii
Connection Timeout, 3-2, 3-5, 3-6 database startup, xxiii
Data Source, 3-2 DataSet, 3-63
DBA Privilege, 3-2 populating, 3-59
Decr Pool Size, 3-2, 3-5, 3-6 populating from a REF CURSOR, 3-59
Enlist, 3-2 populating with generic and custom objects, 3-90
HA Events, 3-2, 3-5 updating, 3-59
Incr Pool Size, 3-2, 3-5, 3-6 updating to database, 3-108
Load Balancing, 3-2, 3-5 DataSet Fill, xxi
Max Pool Size, 3-2, 3-5, 3-6 DataTable, 3-109
Metadata Pooling, 3-2 Datatable properties, 3-108
Min Pool Size, 3-2, 3-5, 3-6 DbCommon classes, 3-18
Password, 3-2 DBlinks, 4-2
Persist Security Info, 3-2 DbProviderFactories class, 2-2, 3-19
Pooling, 3-2, 3-5, 3-6 DbType
Proxy Password, 3-2, 3-14 inference, 3-33
Proxy User Id, 3-2, 3-14 debug tracing, 3-114
Statement Cache Purge, 3-2 default mapping
Statement Cache Size, 3-2 improving, 3-77
User Id, 3-2 dependent unmanaged DLL mismatch, 2-4
Validate Connection, 3-2, 3-5, 3-6 direct path load, 3-28
ConnectionString property, 3-5, 3-6, 5-77 dispose calls, 2-5
Constraints property, 3-108 distributed transactions, 3-22
configuring, 3-109 documentation
context connection, 4-2 .NET, 1-1
Continuous Query Notification, 3-97 Dynamic Enlistment, 3-15
controlling query reexecution, 3-108 dynamic help, 1-1, 2-2
custom classes, 3-78
custom type factories, 3-78
E
custom type factory, 3-81
custom type implementations Easy Connect naming method, 3-4
optional, 3-80 end-to-end tracing, xxiv, 3-16
custom type mapping, 3-81 EnlistDistributedTransaction method, 3-15
custom type mappings enumeration type
specifying, 3-81 OracleDbType, 3-32
specifying with custom type factories, 3-81 error handling, 3-40
specifying with XML, 3-81 example
using, 3-83 connection pooling, 3-5
custom types examples
converting to Oracle UDTS, 3-83 documentation
requirements, 3-79 readme file, 2-2
custom UDT classes, 3-78 ExecuteNonQuery method, 3-59
ExecuteScalar method, 3-59
explicit user connections, 4-1
D EZCONNECT, 3-4
data loss, 3-104
data manipulation
F
using XML, 3-73
data source attribute, 3-4 failover, 3-16
data source enumerator, 3-18 registering an event handler, 3-16
data source enumerators, 3-20 FailoverEvent Enumeration
database description, 11-10
Index-2
FailoverReturnCode Enumeration interface members, 14-410
description, 11-11 interface properties, 14-411
FailoverType Enumeration invalidation message, 3-99
description, 11-12 ensuring persistency of, 3-100
FAN, 3-9 InvalidCastException, 3-48
Fast Application Notification (FAN), 3-9 IOracleArrayTypeFactory Interface
features, 3-1 interface description, 16-33
new, xxi interface members, 16-34
FetchSize property interface methods, 16-35
fine-tuning, 3-56 IOracleCustomType Interface
setting at design time, 3-57 interface description, 16-26
setting at run time, 3-57 interface members, 16-27
using, 3-56 interface methods, 16-28
file locations, 2-2 IOracleCustomTypeFactory Interface
interface description, 16-30
interface members, 16-31
G
interface methods, 16-32
garbage collection, 2-5
geographic data, 3-77
Global Assembly Cache (GAC), 2-2 L
globalization settings, 3-110 large binary datatypes, 3-61
client, 3-111 large character datatypes, 3-61
session, 3-111 limitations and restrictions, 4-2
thread-based, 3-112 Load Balancing, 3-2, 3-9
globalization support, 3-110 load balancing, 2-4
globalization-sensitive operations, 3-113 LOB Connection property, 3-62
Grid environment, 3-9 LOB retrieval, xxv
grid-computing, xxvii, xxviii LOBs
grids, xxvii, xxviii temporary, 3-64
GUI access to ODP.NET, 1-1 updating, 3-63
LOBs updating, 3-63
local transactions, 3-22
H
location data, 3-77
HA Events, 3-2, 3-9, 3-10 LONG and LONG RAW datatypes, 3-62
HA events, 2-4
handling date and time format
manipulating data in XML, 3-73
M
retrieving queries in XML, 3-68 machine.config, 3-114
machine.config file, 2-2
metadata, 3-110
I
method invocation
implicit database connection, 4-1, 4-2, 4-3, 5-83 UDT, 3-91
improving default mapping, 3-77 Microsoft ADO.NET 2.0, 3-18
inference from Value property, 3-34 Microsoft Common Language Runtime (CLR), 1-2
inference of DbType and OracleDbType from Microsoft Hotfix
Value, 3-34 BatchUpdate, 3-27
inference of DbType from OracleDbType, 3-33 Microsoft .NET Framework, 2-1
inference of OracleDbType from DbType, 3-34 Microsoft .NET Framework Class Library, 1-3
inference of types, 3-33 Microsoft Transaction Server, 2-1
InitialLOBFetchSize property, 3-52 MTS, 2-1
InitialLONGFetchSize property, 3-51 multiple notification requests, 3-100
input binding Multiple Oracle Homes, xxix
XMLType column, 3-67 multiple tables
installation, 2-2 changes to, 3-77
Oracle Data Provider for .NET, 2-2
XCopy class, 2-2
integrated help, 2-2
N
interference in OracleParameter class, 3-33 namespace
introduction, overview, 1-3 Oracle.DataAccess.Types, 1-9
INullable Interface native XML support, 3-64
interface description, 14-409 NCLOB, 3-61
Index-3
nested table types, 3-78 statement caching, 3-42
.NET custom types, 3-77 Oracle Data Guard
.NET Framework datatype, 3-46 connecting, 3-9
.NET languages, 1-1 Oracle Data Provider for .NET
.NET products and documentation, 1-1 installing, 2-2
.NET stored procedures and functions, 4-1 system requirements, 2-1
.NET Stream class, 3-62 Oracle Data Provider for .NET assembly, 1-3
.NET type accessors, 3-48 Oracle Database Extensions for .NET, 1-2, 4-1
.NET Types Oracle Developer Tools for Visual Studio, 1-1
inference, 3-33 Oracle Label Security, 3-16
notification framework, 3-99 Oracle native types, 3-46
notification information supported by ODP.NET, 3-48
retrieving, 3-100 Oracle Providers for ASP.NET, 1-2
notification process Oracle RAC
flow, 3-101 connecting, 3-9
notification registration, 3-100 Oracle RAC database
requirements of, 3-101 pool size attributes, 3-11
NULL values Oracle RAC environment, 3-9
retrieving from column, 3-73 Oracle Services for Microsoft Transaction Server, 2-1
number of rows fetched in round-trip Oracle UDT attribute mappings, 3-84
controlling, 3-56 Oracle Universal Installer (OUI), 2-2
Oracle user-defined types, 3-77
Oracle User-Defined Types (UDTs), 3-78
O
Oracle Virtual Private Database (VPD), 3-16
object data type support, 3-77 Oracle XML DB, 3-65
object types, 3-78 Oracle8i Database, ADO.NET 2.0
object-relational data, 3-72 interfaces, 3-18
saving changes from XML data, 3-77 OracleAQAgent
obtaining a REF CURSOR, 3-58, 3-59 constructors, 12-4
obtaining an OracleRefCursor, 3-58 OracleAQAgent Class
obtaining data from an OracleDataReader, 3-47 constructors, 12-4
obtaining LOB data description, 12-2
InitialLOBFetchSize property, 3-52 members, 12-3, 12-39
obtaining LONG and LONG RAW Data, 3-51 properties, 12-6, 12-12
OCI OracleAQDequeueMode Enumeration
statement caching, 3-42 description, 12-83
ODP.NET OracleAQDequeueOptions Class
installing, 2-2 constructor, 12-11
ODP.NET Configuration, 3-114 description, 12-8
ODP.NET LOB classes, 3-61 members, 12-9
ODP.NET Type accessors, 3-50 properties, 12-12
ODP.NET Type classes, 3-46 public methods, 12-18
ODP.NET Type exceptions, 15-1 OracleAQEnqueueOptions Class
ODP.NET Type structures, 3-46, 14-1 constructor, 12-21
ODP.NET Types, 3-46 description, 12-19
overview, 3-46 members, 12-20
ODP.NET within a .NET stored procedure properties, 12-22
limitations and restrictions, 4-2 public methods, 12-24
transaction support, 4-3 OracleAQMessage Class
unsupported SQL commands, 4-6 constructors, 12-28
ODP.NET XML Support, 3-64 description, 12-25
OnChangedEventArgs Class members, 12-26
instance properties, 9-34 properties, 12-30
members, 9-31 OracleAQMessageAvailableEventArgs Class
static fields, 9-32 description, 12-38
static methods, 9-33 members, 12-39
OnChangeEventHandler Delegate properties, 12-40
description, 9-40 OracleAQMessageAvailableEventHandler Delegate
operating system authentication, 3-11 description, 12-47
Oracle Call Interface OracleAQMessageDeliveryMode Enumeration
Index-4
description, 12-84 public methods, 17-14
OracleAQMessageState Enumeration OracleBulkCopyColumnMapping Class
description, 12-86 class description, 17-21
OracleAQMessageType Enumeration constructors, 17-23
description, 12-87 members, 17-22
OracleAQNavigationMode Enumeration properties, 17-26
description, 12-88 OracleBulkCopyColumnMappingCollection Class
OracleAQNotificationGroupingType Enumeration class description, 17-29
description, 12-89 members, 17-31
OracleAQNotificationType Enumeration properties, 17-32
description, 12-90 public methods, 17-33
OracleAQQueue Class OracleBulkCopyOptions Enumeration
constructors, 12-51 description, 17-42
description, 12-48 OracleClientFactory, 2-2
events, 12-78 OracleClientFactory Class
members, 12-49 class description, 7-2
properties, 12-58 class members, 7-4
public methods, 12-64 public methods, 7-6
static methods, 12-51 public properties, 7-5
OracleAQVisibilityMode Enumeration OracleClientFactory class
description, 12-91 instantiating, 3-19
OracleArrayMappingAttribute Class OracleClob Class
constructors, 16-22 class description, 13-73
description, 16-19 constructors, 13-78
members, 16-20 instance methods, 13-88
methods, 16-25 instance properties, 13-82
properties, 16-24 members, 13-75
static methods, 16-23 static fields, 13-80
OracleBFile Class static methods, 13-81
class description, 13-2 OracleCollectionType Enumeration, 5-354
constructors, 13-7 OracleCommand
instance methods, 13-19 ArrayBindCount property, 3-39
instance properties, 13-12 constructors, 5-7
members, 13-4 InitialLOBFetchSize property, 3-52
static fields, 13-9 InitialLONGFetchSize property, 3-51
static methods, 13-11 Transaction property, 3-30
OracleBinary Structure OracleCommand Class
constructor, 14-7 ArrayBindCount, 5-13
description, 14-2 class description, 5-2
instance methods, 14-26 ExecuteScalar method, 3-59
members, 14-4 FetchSize property, 3-56
properties, 14-23 members, 5-4
static fields, 14-8 properties, 5-10
static methods, 14-9 public methods, 5-27, 12-18
static operators, 14-15 RowSize property, 3-57
static type conversion operators, 14-21 static methods, 5-9
OracleBlob Class OracleCommand object, 3-30
class description, 13-38 OracleCommand properties
constructors, 13-43 ArrayBindCount, 3-39
instance methods, 13-53 OracleCommand Transaction object, 3-30
instance properties, 13-47 OracleCommandBuilder Class, 3-110
members, 13-40 class description, 5-41
static fields, 13-45 constructors, 5-47
static methods, 13-46 events, 5-63
OracleBulkCopy Class members, 5-44
class description, 17-2 properties, 5-53
constructors, 17-5 public methods, 5-58
events, 17-20 static methods, 5-49
members, 17-3 updating dataset, 3-108
properties, 17-9 OracleConnection
Index-5
ClearAllPools property, 3-7 typed accessors, 3-48
ClearPool property, 3-7 OracleDataReader Class
ClientId property, 3-16 class description, 5-150
events, 5-110 FetchSize property, 3-56
OracleConnection Class populating, 3-58
class description, 5-64 properties, 5-158
constructors, 5-69 public methods, 5-169
members, 5-66 static methods, 5-157
obtaining a reference, 3-66 OracleDataReader Class SchemaTable, 5-204
properties, 5-76 OracleDataSource Enumerator class
public methods, 5-89 using, 3-20
static methods, 5-73 OracleDataSourceEnumerator Class
OracleConnection class class description, 7-36
GetSchema methods, 3-21 class members, 7-38
OracleConnectionStringBuilder Class public methods, 7-39
class description, 7-10 OracleDate Structure
class members, 7-13 constructors, 14-34
constructors, 7-16 description, 14-29
public methods, 7-33 members, 14-31
public properties, 7-18 methods, 14-60
OracleConnectionStringBuilder class properties, 14-56
using, 3-20 static fields, 14-39
OracleCustomTypeMappingAttribute Class static methods, 14-41
constructors, 16-6 static operators, 14-47
description, 16-2 static type conversions, 14-52
members, 16-4 OracleDBShutdownMode Enumeration
methods, 16-9 description, 5-355
properties, 16-8 OracleDBStartupMode Enumeration
static methods, 16-7 description, 5-356
Oracle.DataAccess.Client namespace, 1-3 OracleDbType
Oracle.DataAccess.dll, 1-3 inference, 3-33
Oracle.DataAccess.Types namespace, 1-3, 1-9 OracleDbType enumeration, 3-33
OracleDataAdapter, 3-104 OracleDbType enumeration type, 3-32, 5-357
constructors, 5-119 OracleDecimal Structure
members, 5-116 constructors, 14-72
SafeMapping Property, 3-106 description, 14-65
SelectCommand property, 3-59 instance methods, 14-133
OracleDataAdapter Class, 5-114 members, 14-67
events, 5-134 properties, 14-129
FillSchema method, 3-110 static comparison methods, 14-82
properties, 5-123 static comparison operators, 14-112
public methods, 5-129 static logarithmic methods, 14-101
SelectCommand property, 3-110 static manipulation methods, 14-87
static methods, 5-122 static operators, .NET Type to
OracleDataAdapter class OracleDecimal, 14-120
FillSchema method, 3-109 static operators, OracleDecimal to .NET, 14-124
Requery property, 3-108 static trignonmetric methods, 14-106
SelectCommand property, 3-109 OracleDependency Class
OracleDataAdapter Safe Type Mapping, 3-104 change notification, 3-99
OracleDatabase Class class description, 9-2
class description, 5-138 constructors, 9-5
constructor, 5-141 database change notification, 3-97
members, 5-140 events, 9-21
properties, 5-142 instance methods, 9-18
public methods, 5-143 instance properties, 9-12
Shutdown method, 5-143 members, 9-3
Startup method, 5-147 static fields, 9-9
OracleDataReader, 3-47, 3-51 static methods, 9-11
members, 5-153 OracleError Class
retrieving UDTs from, 3-86 ArrayBindIndex, 5-218
Index-6
class description, 5-214 static operators, 14-194
members, 5-216 type conversions, 14-201
methods, 5-221 OracleNotificationEventArgs Class
properties, 5-218 change notification, 3-99
static methods, 5-217 class description, 9-30
OracleErrorCollection instance methods, 9-39
members, 5-224 OracleNotificationInfo Enumeration
properties, 5-226 description, 9-44
public methods, 5-227 OracleNotificationRequest Class
static methods, 5-225 change notification, 3-99
OracleErrorCollection Class, 5-222 class description, 9-22
OracleException database change notification, 3-97
members, 5-230 instance methods, 9-29
methods, 5-236 instance properties, 9-25
properties, 5-233 members, 9-23
static methods, 5-232 static methods, 9-24
OracleException Class, 5-228 OracleNotificationSource Enumeration
OracleFailoverEventArgs description, 9-43
members, 11-5 OracleNotificationType Enumeration
properties, 11-7 description, 9-42
public methods, 11-8 OracleNullValueException Class
OracleFailoverEventHandler Delegate class description, 15-11
description, 11-9 constructors, 15-14
OracleGlobalization Class members, 15-12
class description, 10-2 methods, 15-16, 15-18
members, 10-4 properties, 15-17
properties, 10-12 OracleObjectMappingAttribute Class
public methods, 10-22 constructors, 16-13
OracleHAEventArgs Class description, 16-10
description, 8-2 members, 16-11
members, 8-3 methods, 16-18
properties, 8-4 properties, 16-16
OracleHAEventHandler Delegate static methods, 16-15
description, 8-8 OracleParameter
OracleHAEventSource Enumeration array bind properties, 3-40
description, 8-9 ArrayBindSize property, 3-40, 5-263
OracleHAEventStatus Enumeration ArrayBindStatus property, 3-40, 5-264
description, 8-10 constructors, 5-250
OracleInfoMessageEventArgs inferences of types, 3-33
members, 5-240 members, 5-248
properties, 5-242 properties, 5-261
public methods, 5-244 public methods, 5-278
static methods, 5-241 static methods, 5-261
OracleInfoMessageEventHandler Delegate, 5-245 OracleParameter array bind feature, 3-39
OracleIntervalDS Structure OracleParameter Class, 5-246
constructors, 14-144 Value, 3-34
description, 14-139 OracleParameter object, 3-31
members, 14-141 OracleDbType enumerated values, 3-32
methods, 14-174 OracleParameter property
properties, 14-169 ArrayBindSize, 3-36
static methods, 14-151 ArrayBindStatus, 3-36
static operators, 14-158 CollectionType, 3-36
type conversions, 14-166 Size, 3-36
OracleIntervalYM Structure Value, 3-36
constructors, 14-182 OracleParameterCollection
description, 14-177 members, 5-283
members, 14-179 public methods, 5-289
methods, 14-188, 14-207 static methods, 5-285
properties, 14-204 OracleParameterCollection Class, 5-281
static fields, 14-186 OracleParameterStatus enumeration type, 3-42,
Index-7
5-359 properties, 14-233
OraclePermission Class static fields, 14-220
constructor, 5-310 static methods, 14-221
members, 5-308 static operators, 14-226
public methods, 5-313 type conversions, 14-231
public properties, 5-312 OracleTimeStamp Structure
static methods, 5-311 constructors, 14-247
Oraclepermission Class description, 14-241
description, 5-307 members, 14-243
OraclePermissionAttribute Class methods, 14-283
constructor, 5-319 properties, 14-278
description, 5-316 static methods, 14-256
members, 5-317 static operators, 14-263
public methods, 5-322 static type conversions, 14-272
public properties, 5-321 OracleTimeStampLTZ Structure
static methods, 5-320 constructors, 14-300
OracleRef Class description, 14-294
class description, 16-51 members, 14-296
class members, 16-52 methods, 14-337
constructors, 16-54 properties, 14-332
instance methods, 16-62 static fields, 14-307
instance properties, 16-58 static methods, 14-309
static fields, 16-56 static operators, 14-317
static methods, 16-57 static type conversions, 14-326
OracleRefCursor, 3-58 OracleTimeStampTZ Structure
OracleRefCursor Class constructors, 14-355
class description, 13-113 description, 14-349
instance methods, 13-121 members, 14-351
members, 13-116 methods, 14-397
populating from a REF CURSOR, 3-59 properties, 14-391
properties, 13-118 static fields, 14-367
static methods, 13-117 static methods, 14-369
OracleRowsCopiedEventArgs Class static operators, 14-376
class description, 17-44 static type conversions, 14-385
constructors, 17-46 OracleTransaction
members, 17-45 members, 5-342
properties, 17-47 properties, 5-344
OracleRowsCopiedEventHandler Delegate public methods, 5-346
description, 17-43 static methods, 5-343
OracleRowUpdatedEventArgs OracleTransaction Class
constructor, 5-326 class description, 5-339
members, 5-324 OracleTruncateException Class
properties, 5-328 class description, 15-19
public methods, 5-329 constructors, 15-22
static methods, 5-327 members, 15-20
OracleRowUpdatedEventArgs Class, 5-323 methods, 15-26
OracleRowUpdatedEventHandler Delegate, 5-330 properties, 15-25
OracleRowUpdatingEventArgs static methods, 15-24
constructor, 5-334 OracleTypeException Class
members, 5-332 class description, 15-2
properties, 5-336 constructors, 15-5
public methods, 5-337 members, 15-3
static methods, 5-335 properties, 15-8
OracleRowUpdatingEventArgs Class, 5-331 static methods, 15-7
OracleRowUpdatingEventHandler Delegate, 5-338 OracleUdt Class
OracleString Structure description, 16-37
constructors, 14-215 members, 16-38
description, 14-210 static methods, 16-39
members, 14-212 OracleUdtFetchOption Enumeration
methods, 14-236 description, 16-73
Index-8
OracleUdtStatus Enumeration port
description, 16-74 listen for database notifications, 2-4
OracleXmlCommandType Enumeration, 6-2 port number
OracleXmlQueryProperties Class defining listener, 3-100
class description, 6-3 porting
constructors, 6-8 client application to .NET stored procedure, 4-6
members, 6-7 preventing data loss, 3-104, 3-106
properties, 6-9 PrimaryKey property, 3-108
public methods, 6-12 configuring, 3-109
OracleXmlSaveProperties Class, 6-13 privileged connections, 3-12
constructors, 6-17 promotable transactions, xxii, 3-22
members, 6-16 properties
properties, 6-18 ClientId property, 3-16
public methods, 6-22 provider factory classes, 3-18, 3-19
OracleXmlStream Class provider independence, 3-18
class description, 6-23 proxy authentication, 3-14
constructors, 6-26
instance methods, 6-32
Q
instance properties, 6-28
members, 6-24 query result set
static methods, 6-27 retrieving as XML, 3-68
OracleXmlType Class, 3-66
class description, 6-37 R
constructors, 6-40
instance methods, 6-49 RAC database
instance properties, 6-44 pool size attributes, 3-11
members, 6-38 RAC environment, 3-9
static methods, 6-43 REF CURSOR
behavior of ExecuteScalar method, 3-59
obtaining, 3-58, 3-59
P passing to stored procedure, 3-60
parameter binding, 3-31 populating DataSet from, 3-59
parameter binding with OracleParameter, 3-88 populating from OracleDataReader, 3-58
parameter context caching, xxiv registry entries, 3-114
password expiration, 3-12 release Oracle8i (8.1.7), 3-73
passwords in code examples, xix release Oracle9i(9.0.x), 3-73
performance, 3-42 Requery property, 3-108
array binding, 3-39 round-trip, 3-39
connection pooling, 3-5 RowSize property, 3-57
fine-tuning FetchSize, 3-56 Runtime Connection Load Balancing, 3-9
number of rows fetched, 3-56
Obtaining LOB Data, 3-52 S
performance counters, 2-4
connection pool, 3-7 Safe Type Mapping, 3-104
instance names of, 3-8 SafeMapping Property, 3-106
publishing, 3-7 Samples, 1-11
using app.config entry, 3-8 samples, 2-2
PL/SQL Associative Array binding, 3-36 UDT, 16-1
PL/SQL Index-By Tables, 3-36 saving change using an XML document, 3-75
PL/SQL language, 3-58 saving changes
PL/SQL REF CURSOR, 3-58 using XML data, 3-73
PL/SQL REF CURSOR and OracleRefCursor, 3-58 schema metadata
PLSQLAssociativeArray, 5-354 customizing metadata, 3-21
populating an OracleDataReader from a REF SchemaTable, 5-204
CURSOR, 3-58 search order
populating an OracleRefCursor from a REF unmanaged DLLs, 2-3
CURSOR, 3-59 SecureFiles, xxv, 3-61
populating the DataSet from a REF CURSOR, 3-59 security enhancements, xxii
populating the DataSet with generic and custom SelectCommand property, 3-59
objects, 3-90 Self-Tuning, xxi
session globalization parameters, 3-114
Index-9
session globalization settings, 3-111 UdtCacheSize, 3-91
shema discovery UDTs, 3-77
support, 3-18 collection types, 3-78
Shutdown method, 5-143 configuration settings, 3-91
shutdown, database, xxiii object types, 3-78
simple application, 1-11 parameter binding with OracleParameter, 3-88
Size property, 3-36 retrieving from OracleDataReader, 3-86
SQL commands samples, 16-1
unsupported, 4-6 UDTs (Oracle User-Defined Types), 3-78
Startup method, 5-147 UdtTypeName property, 3-88
startup, database, xxiii unique columns, 3-51, 3-52
Statement Caching unique constraint, 3-51, 3-52
connection string attributes, 3-42 unique index, 3-51, 3-52
methods and properties, 3-43 UniqueConstraint, 3-109
Statement Cache Purge, 3-42 uniqueness
Statement Cache Size, 3-42 in updating DataSet to database, 3-108
StatementCacheWithUdts, 3-91 uniqueness in DataRows, 3-109
stored procedures and functions, 3-60, 4-1 unmanaged DLLs
Stream class, 3-62 mismatch, 2-4
support comparison search order, 2-3
client application versus .NET stored unmanged DLLs
procedure, 4-6 config support, 2-3
SYSDBA privileges, 3-12 unsupported SQL commands, 4-6
SYSOPER privileges, 3-12 updating
system requirements LOBs, 3-63
Oracle Data Provider for .NET, 2-1 updating a DataSet obtained from a REF
System.Data.Common, 3-18 CURSOR, 3-59
System.Transactions support, 3-22 updating LOBs using a DataSet, 3-63
updating LOBs using ODP.NET LOB objects, 3-63
updating LOBs using OracleCommand and
T
OracleParameter, 3-63
table or view updating without PrimaryKey and
special characters in, 3-75 Constraints, 3-110
TAF, 3-16 user-defined types, 3-77
TAF callback support, 3-16 using FetchSize property, 3-56
Temporary LOBs, 3-64
thread globalization settings, 3-113
Thread.Abort method, 2-5
V
thread-based globalization settings, 3-112 Value property, 3-36
tips for ODP.NET, 2-5 VARRAY types, 3-78
TNS alias, 3-4 Virtual Private Database(VPD), 3-16
tracing Visual Studio
end-to-end, xxiv documentation, 2-2
tracing attributes, 3-16
Transaction object, 3-30
W
Transaction property, 3-30
transaction support, 4-3 web.config, 3-114
transactions Windows registry, 2-3
commit, 3-77
TransactionScope, 3-22 X
Transparent Application Failover (TAF), 3-16
troubleshooting, 3-114 XML
typed OracleDataReader accessors, 3-48 characters with special meaning, 3-68
data manipulation using, 3-73
XML data
U saving changes using, 3-73
UDT updating in OracleXmlType, 3-68
method invocation, 3-91 XML Database, 3-64
UDT metadata retrieval from XML DB, 3-64, 3-65
OracleDataReader, 3-87 XML element name
case-sensitivity in, 3-75
Index-10
XML Element Name to Column Name
Mapping, 3-75
XML related classes, 6-1
XML related enumerations, 6-1
XML Support, 3-64
XML to specify custom type mappings, 3-82
XMLQuery, 3-65
XMLTable, 3-65
XMLType column
as a .NET String, 3-66
fetching into the DataSet, 3-66
updating with OracleCommand, 3-67
XMLType columns
setting to NULL, 3-67
XQUERY, 3-65
XQuery
support, 3-65
XQuery language, 3-65
Index-11
Index-12