Oracle Call Interface Programmer’S Guide, Release 9.0.1 Part No
Total Page:16
File Type:pdf, Size:1020Kb
Oracle Call Interface Programmer’s Guide Release 9.0.1 June 2001 Part No. A89857-01 Oracle Call Interface Programmer’s Guide, Release 9.0.1 Part No. A89857-01 Copyright © 1996, 2001, Oracle Corporation. All rights reserved. Primary Authors: Jack Melnick Contributing Author: Eric Belden, Phil Locke Contributors: G. Arora, P. Balaji, M. Bastawala, S. Chandrasekaran, D. Chatterjee, E. Chen, L. Chidambaran, S. Gollapudi, G. Govindarajan, W. He, T. Hoang, R.-S. Hwu, M. Joglekar, S. Kaluskar, R. Kambo, R. Kasamsetty, A. Katti, S. Kotsovolos, V. Krishnamurthy, S. Krishnaswamy, R. Krishnan, S. Kumar, S. Lari, C. Lei, C. Lim, Meghna Mehta, Sambit Mishra, Shailendra Mishra, P. Mitra, K. Mohan, R. Murthy, R. Ratnam, P. Reilly, A. Roy, D. Saha, E. Soylemez, A. Surpur, A. Swaminathan, P. Tucker, S. Vedala, Wei Wang, R. Wessman, D. Wong Graphic Designer: Valarie Moore 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 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 SQL*Forms, SQL*Net, Oracle NetSolutions, Oracle Secure Network Services, SQL*Plus, Oracle Call Interface, Oracle7, Oracle7 Server, Oracle8, Oracle8i, Oracle9i, Oracle Forms, PL/SQL, Pro*C, Pro*C/C++, Pro*COBOL, Net8, Oracle Store, and Trusted Oracle are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners. Oracle Call Interface Programmer’s Guide Contents Send Us Your Comments ............................................................................................................. xxxiii Preface....................................................................................................................................................... xxxv Audience ........................................................................................................................................... xxxvi Organization..................................................................................................................................... xxxvi Related Documentation ........................................................................................................................ xl Conventions........................................................................................................................................... xli Documentation Accessibility ............................................................................................................. xliii What’s New in Oracle Call Interface?........................................................................................ xlv Oracle9i Release 1 (9.0.1) New Features in Oracle Call Interface ................................................ xlvi Oracle9i Release 9.0.0 New Features in Oracle Call Interface..................................................... xlvii Oracle8i Release 2 (8.1.6) New Features in Oracle Call Interface ..................................................... l Part I OCI Concepts 1 Introduction and Upgrading Overview of OCI................................................................................................................................. 1-2 Advantages of OCI....................................................................................................................... 1-3 Building an OCI Application ...................................................................................................... 1-3 Parts of OCI ................................................................................................................................... 1-4 Procedural and Non-Procedural Elements............................................................................... 1-5 Object Support .............................................................................................................................. 1-6 SQL Statements............................................................................................................................. 1-7 iii Encapsulated Interfaces ............................................................................................................. 1-12 Simplified User Authentication and Password Management.............................................. 1-12 Extensions to Improve Application Performance and Scalability....................................... 1-13 OCI Object Support .................................................................................................................... 1-14 Client-Side Object Cache ........................................................................................................... 1-14 Associative and Navigational Interfaces................................................................................. 1-14 Runtime Environment for Objects............................................................................................ 1-15 Type Management, Mapping and Manipulation Functions ................................................ 1-16 Object Type Translator............................................................................................................... 1-16 OCI Support for Oracle Advanced Queuing .......................................................................... 1-17 XA Library Support.................................................................................................................... 1-17 Simplified Migration of Existing Applications....................................................................... 1-17 Compatibility, Upgrading, and Migration................................................................................... 1-18 Obsolescent OCI Routines......................................................................................................... 1-18 OCI Routines Not Supported.................................................................................................... 1-20 Compatibility............................................................................................................................... 1-21 Upgrading.................................................................................................................................... 1-22 2 OCI Programming Basics Overview of OCI Programming....................................................................................................... 2-2 OCI Program Structure ...................................................................................................................... 2-2 OCI Data Structures ........................................................................................................................... 2-5 Handles ................................................................................................................................................. 2-5 Allocating and Freeing Handles................................................................................................. 2-6 Environment Handle.................................................................................................................... 2-9 Error Handle.................................................................................................................................. 2-9 Service Context and Associated Handles.................................................................................. 2-9 Statement Handle, Bind Handle, and Define Handle ........................................................... 2-10 Describe Handle.........................................................................................................................