Tài liệu Oracle C++ Call Interface Programmer''''s Guide docx

Oracle® C++ Call Interface Programmer's Guide 10g Release 1 (10.1) Part No. B10778-01 December 2003 Oracle C++ Call Interface Programmer’s Guide, 10g Release 1 (10.1) Part No. B10778-01 Copyright © 1999, 2003 Oracle Corporation. All rights reserved. Primary Author: Roza Leyderman Contributors: Sandeepan Banerjee, Subhranshu Banergee, Kalyanji Chintakayala, Krishna Itikarlapalli, Shankar Iyer, Maura Joglekar, Ravi Kasamsetty, Srinath Krishnaswamy, Shoaib Lari, Geoff Lee, Chetan Maiya, Rekha Vallam The Programs (which include both the software and documentation) contain proprietary information of Oracle Corporation; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent and other intellectual and industrial property laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation. If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on behalf of the U.S. Government, the following notice is applicable: Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the Programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065. The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the Programs. Oracle is a registered trademark, and Oracle Store, PL/SQL, and SQL*Plus are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners. iii Contents Send Us Your Comments xvii Preface xix Audience . xix Organization xx Related Documentation xxi Conventions . xxii Documentation Accessibility xxv What's New in Oracle C++ Call lnterface? xxvii New Features for 10g Release 1 (10.1) xxvii 1 Introduction to OCCI Overview of OCCI 1-1 Benefits of OCCI . 1-2 Building an OCCI Application . 1-2 Functionality of OCCI 1-3 Procedural and Nonprocedural Elements 1-4 Instant Client Feature . 1-5 Benefits of Instant Client . 1-5 Installing Instant Client . 1-5 Using Instant Client 1-7 Patching Instant Client Shared Libraries on Unix . 1-7 Database Connection Names for Instant Client . 1-7 iv Environment Variables for OCCI Instant Client 1-8 Processing of SQL Statements 1-9 DDL Statements 1-9 Control Statements . 1-10 DML SQL Statements . 1-10 Queries . 1-11 Overview of PL/SQL . 1-11 Special OCCI/SQL Terms 1-12 Object Support 1-13 Client-Side Object Cache . 1-14 Runtime Environment for Objects 1-14 Associative and Navigational Interfaces . 1-15 Metadata Class 1-15 Object Type Translator Utility 1-16 2 Relational Programming Connecting to a Database 2-1 Creating and Terminating an Environment . 2-2 Opening and Closing a Connection . 2-3 Connection Pooling 2-3 Creating a Connection Pool . 2-4 Stateless Connection Pooling 2-6 Executing SQL DDL and DML Statements . 2-10 Creating a Statement Object 2-10 Creating a Statement Object to Execute SQL Commands . 2-10 Reusing a Statement Object . 2-11 Terminating a Statement Object . 2-11 Types of SQL Statements in the OCCI Environment 2-11 Standard Statements . 2-12 Parameterized Statements . 2-12 Callable Statements 2-13 Streamed Reads and Writes 2-15 Modifying Rows Iteratively 2-18 Executing SQL Queries 2-20 Result Set 2-20 v Specifying the Query 2-21 Optimizing Performance by Setting Prefetch Count . 2-22 Executing Statements Dynamically . 2-22 Status Definitions 2-23 Committing a Transaction . 2-26 Statement Caching 2-26 Exception Handling 2-29 Null and Truncated Data . 2-31 Advanced Relational Techniques 2-32 Sharing Connections 2-32 Optimizing Performance . 2-36 3 Object Programming Overview of Object Programming 3-1 Working with Objects in OCCI . 3-2 Persistent Objects 3-2 Transient Objects 3-4 Values . 3-5 Representing Objects in C++ Applications . 3-5 Creating Persistent and Transient Objects 3-5 Creating Object Representations using the OTT Utility . 3-6 Developing an OCCI Object Application 3-7 Basic Object Program Structure 3-7 Basic Object Operational Flow 3-8 Migrating C++ Applications Using OCCI . 3-12 Steps for Migration . 3-12 Overview of Associative Access 3-12 Using SQL to Access Objects 3-13 Inserting and Modifying Values 3-13 Overview of Navigational Access 3-14 Retrieving an Object Reference (REF) from the Database Server . 3-14 Pinning an Object 3-15 Manipulating Object Attributes 3-16 Marking Objects and Flushing Changes . 3-16 Marking an Object as Modified (Dirty) . 3-16 vi Recording Changes in the Database . 3-16 Garbage Collection in the Object Cache 3-17 Transactional Consistency of References 3-18 Overview of Complex Object Retrieval . 3-18 Retrieving Complex Objects 3-19 Prefetching Complex Objects 3-21 Working with Collections . 3-22 Fetching Embedded Objects 3-23 Nullness 3-23 Using Object References . 3-24 Deleting Objects from the Database . 3-24 Type Inheritance 3-24 Substitutability 3-26 NOT INSTANTIABLE Types and Methods . 3-26 OCCI Support for Type Inheritance . 3-27 OTT Support for Type Inheritance . 3-27 A Sample OCCI Application . 3-28 4 Datatypes Overview of Oracle Datatypes . 4-1 OCCI Type and Data Conversion 4-2 Internal Datatypes 4-2 Character Strings and Byte Arrays . 4-4 Universal Rowid (UROWID) 4-4 External Datatypes 4-5 Description of External Datatypes . 4-8 Data Conversions 4-21 Data Conversions for LOB Datatypes 4-23 Data Conversions for Date, Timestamp, and Interval Datatypes 4-23 5 Metadata Overview of Metadata 5-1 Notes on Types and Attributes . 5-2 Describing Database Metadata 5-3 Metadata Code Examples 5-4 vii Attribute Reference 5-8 Parameter Attributes 5-8 Table and View Attributes 5-9 Procedure, Function, and Subprogram Attributes 5-10 Package Attributes 5-11 Type Attributes . 5-11 Type Attribute Attributes 5-13 Type Method Attributes 5-14 Collection Attributes 5-15 Synonym Attributes . 5-16 Sequence Attributes . 5-16 Column Attributes 5-17 Argument and Result Attributes 5-18 List Attributes . 5-19 Schema Attributes 5-20 Database Attributes 5-20 6 Object Type Translator Utility Overview of the Object Type Translator Utility . 6-1 Using the OTT Utility 6-2 Creating Types in the Database . 6-3 Invoking the OTT Utility 6-3 Specifying OTT Parameters 6-3 Invoking the OTT Utility on the Command Line 6-4 OTT Utility Parameters 6-6 Where OTT Parameters Can Appear . 6-15 File Name Comparison Restriction 6-16 Using the INTYPE File . 6-17 Overview of the INTYPE File . 6-17 Structure of the INTYPE File . 6-18 Nested #include File Generation 6-21 OTT Utility Datatype Mappings . 6-24 Default Name Mapping . 6-30 Overview of the OUTTYPE File . 6-31 The OTT Utility and OCCI Applications 6-32 viii C++ Classes Generated by the OTT Utility . 6-34 Map Registry Function . 6-35 Extending C++ Classes 6-36 Carrying Forward User Added Code 6-37 Properties of OTT Markers 6-37 Using OTT Markers 6-39 7 Globalization and Unicode Support Overview of Globalization and Unicode Support . 7-1 Specifying Charactersets . 7-1 Datatypes for Globalization and Unicode Support . 7-2 UString Datatype 7-2 Multibyte and UTF16 data 7-3 CLOB and NCLOB Datatypes . 7-4 Objects and OTT Support . 7-5 8 Oracle Streams Advanced Queuing Overview of Oracle Streams Advanced Queuing 8-1 AQ Implementation in OCCI . 8-2 Message 8-3 Agent 8-3 Producer . 8-4 Consumer . 8-4 Listener . 8-4 Subscription . 8-4 Creating Messages 8-5 Message Payloads . 8-5 Message Properties . 8-6 Enqueuing Messages 8-8 Dequeuing Messages . 8-8 Dequeuing Options 8-9 Listening for Messages 8-10 Registering for Notification 8-10 Publish-Subscribe Notifications 8-11 Notification Callback 8-14 ix Message Format Transformation . 8-15 9 Oracle XA Library Application Development with XA and OCCI . 9-1 APIs for XA Support 9-2 10 OCCI Application Programming Interface OCCI Classes and Methods 10-2 Agent Class 10-10 AnyData Class . 10-14 Bfile Class . 10-26 Blob Class . 10-35 Bytes Class 10-45 Clob Class . 10-48 Connection Class 10-61 ConnectionPool Class 10-72 Consumer Class . 10-78 Date Class . 10-89 Environment Class 10-102 IntervalDS Class . 10-118 IntervalYM Class 10-131 Listener Class . 10-142 Map Class . 10-145 Message Class 10-147 MetaData Class 10-158 NotifyResult Class 10-166 Number Class 10-168 PObject Class . 10-194 Producer Class . 10-201 Ref Class . 10-207 RefAny Class . 10-214 ResultSet Class 10-219 SQLException Class . 10-245 StatelessConnectionPool Class 10-249 Statement Class . 10-260 x Stream Class . 10-316 Subscription Class 10-319 Timestamp Class . 10-327 Index [...]... is at http://forums .oracle. com/forums/forum.jsp?forum=168 ■ Demos at $ORACLE_ HOME/rdbms/demo ■ Oracle Database Concepts ■ Oracle Database SQL Reference ■ Oracle Database Application Developer's Guide - Object-Relational Features ■ Oracle Database New Features ■ Oracle Call Interface Programmer's Guide ■ Oracle Database Administrator's Guide ■ Oracle Streams Advanced Queuing User’s Guide and Reference... may contain links to Web sites of other companies or organizations that Oracle does not own or control Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites xxv xxvi What's New in Oracle C++ Call lnterface? This section describes new features in Oracle C++ Call Interface Programmer's Guide and supplies pointers to additional information New Features for... your local Oracle Support Services xvii xviii Preface The Oracle C++ Call Interface (OCCI) is an application programming interface (API) that allows applications written in C++ to interact with one or more Oracle database servers OCCI gives your programs the ability to perform the full range of database operations that are possible with an Oracle database server, including SQL statement processing... Documentation Accessibility Audience The Oracle C++ Call Interface Programmer's Guide is intended for programmers, system analysts, project managers, and other Oracle users who perform, or are interested in learning about, the following tasks: ■ Design and develop database applications in the Oracle environment ■ Convert existing database applications to run in the Oracle environment ■ Manage the development... Oracle C++ Call Interface (OCCI) and introduces terminology used in discussing OCCI You are provided with the background information needed to develop C++ applications that run in an Oracle environment This chapter contains these topics: ■ Overview of OCCI ■ Instant Client Feature ■ Processing of SQL Statements ■ Overview of PL/SQL ■ Special OCCI/SQL Terms ■ Object Support Overview of OCCI Oracle C++. .. not available, only then is ORACLE_ HOME used and a full client installation is assumed When set, ORACLE_ HOME should be a valid operating system path name that identifies a directory If Dynamic User callback libraries are to be loaded, then as this guide specifies, the callback package has to reside in ORACLE_ HOME/lib on Solaris or ORACLE_ HOME\bin on Windows Therefore, ORACLE_ HOME should be set in... interface to manipulate database objects of user-defined types as C++ class instances Building an OCCI Application As Figure 1-1 shows, you compile and link an OCCI program in the same way that you compile and link a nondatabase application 1-2 Oracle C++ Call Interface Programmer's Guide Overview of OCCI Figure 1–1 The OCCI Development Process Oracle supports most popular third-party compilers The details... SQL Statements ■ Overview of PL/SQL ■ Special OCCI/SQL Terms ■ Object Support Overview of OCCI Oracle C++ Call Interface (OCCI) is an Application Programming Interface (API) that provides C++ applications access to data in an Oracle database OCCI enables C++ programmers to utilize the full range of Oracle database operations, including SQL statement processing and object manipulation OCCI provides for:... seed database, which is installed by default when you install Oracle Refer to Oracle Database Sample Schemas for information on how these schemas were created and how you can use them yourself In North America, printed documentation is available for sale in the Oracle Store at http://oraclestore .oracle. com/ Other customers can contact their Oracle representative to purchase printed documentation xxi... (bind) variables, as follows: SELECT name FROM employees WHERE empno = :empnumber 1-4 Oracle C++ Call Interface Programmer's Guide Instant Client Feature In this SQL statement, empnumber is a placeholder for a value that will be supplied by the application In an OCCI application, you can also take advantage of PL/SQL, Oracle' s procedural extension to SQL The applications you develop can be more powerful . Oracle C++ Call Interface Programmer's Guide 10g Release 1 (10.1) Part No. B10778-01 December 2003 Oracle C++ Call Interface Programmer’s Guide, . 10-328 xvii Send Us Your Comments Oracle C++ Call Interface Programmer’s Guide, 10g Release 1 (10.1) Part No. B10778-01 Oracle Corporation welcomes your