Oracle Call Interface Programmer’s Guide, Volumes 1 & 2 Release 8.0 December 1997 Part No. A58234-01 Oracle Call Interface Programmer’s Guide Part No. A58234-01 Release 8.0 Copyright © 1997, Oracle Corporation. All rights reserved. Primary Author: Phil Locke Contributors: John Bellemore, John Boonleungtomnu, Sashi Chandrasekaran, Debashish Chatterjee, Ernest Chen, Calvin Cheng, Luxi Chidambaran, Diana Foch-Lorentz, Sreenivas Gollapudi, Brajesh Goyal, Radhakrishna Hari, Don Herkimer, Amit Jasuja, Sanjay Kaluskar, Kai Korot, Susan Kotsovolos, Srinath Krishnaswamy, Ramkumar Krishnan, Sanjeev Kumar, Thomas Kurian, Paul Lane, Shoaib Lari, Chon Lei, Nancy Liu, Valarie Moore, Tin Nguyen, Denise Oertel, Rosanne Park, Jacqui Pons, Den Raphaely, Anindo Roy, Tim Smith, Ekrem Soylemez, Ashwini Surpur, Sudheer Thakur, Alan Thiessen, Peter Vasterd, Randall Whitman, Joyo Wijaya, Allen Zhao This book is dedicated to the memory of Denise Elizabeth Oertel. 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 property law. Reverse engineering of the Programs is prohibited. The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be licensee's responsibility to take all appropriate fail-safe, back up, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle disclaims liability for any damages caused by such use of the Programs. 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. No part of this document 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 this Program is delivered to a U.S. Government Agency of the Department of Defense, then it is delivered with Restricted Rights and the following legend is applicable: Restricted Rights Legend Programs delivered subject to the DOD FAR Supplement are 'commercial computer software' and use, duplication and disclosure of the Programs 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-14, Rights in Data -- General, including Alternate III (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065. Oracle, SQL*Forms, SQL*Net, and SQL*Plus are registered trademarks of Oracle Corporation, Redwood Shores, California. Oracle Call Interface, Oracle7, Oracle7 Server, Oracle8, Oracle Forms, PL/SQL, Pro*C, Pro*C/C++, Pro*COBOL, Net8, and Trusted Oracle are trademarks of Oracle Corporation, Redwood Shores, California. All other products or company names are used for identification purposes only, and may be trademarks of their respective owners. Contents Send Us Your Comments .............................................................................................................. xxvii Preface........................................................................................................................................................ xxix Purpose of this Guide ........................................................................................................................ xxx Audience............................................................................................................................................... xxx Feature Coverage and Availability ................................................................................................. xxxi How to Use this Guide...................................................................................................................... xxxi How this Guide Is Organized ........................................................................................................ xxxii Conventions Used in this Guide ................................................................................................... xxxv Your Comments Are Welcome....................................................................................................... xxxvi Part I Basic OCI Concepts 1 Introduction and New Features The Oracle Call Interface .................................................................................................................. 1-2 SQL Statements................................................................................................................................... 1-4 Data Definition Language ........................................................................................................... 1-4 Control Statements ....................................................................................................................... 1-5 iii Data Manipulation Language ..................................................................................................... 1-5 Queries ........................................................................................................................................... 1-5 PL/SQL .......................................................................................................................................... 1-6 Embedded SQL ............................................................................................................................. 1-7 Special OCI/SQL Terms..................................................................................................................... 1-8 Object Support in the OCI ................................................................................................................ 1-8 Parts of the OCI ................................................................................................................................. 1-10 Release 8.0 New Features................................................................................................................. 1-10 Obsolescent and Obsolete OCI Calls............................................................................................ 1-11 Compiling and Linking ................................................................................................................... 1-11 2 OCI Programming Basics Overview............................................................................................................................................... 2-2 OCI Program Structure ...................................................................................................................... 2-3 OCI Data Structures ........................................................................................................................... 2-5 Handles ................................................................................................................................................. 2-6 Allocating and Freeing Handles................................................................................................. 2-7 Environment Handle.................................................................................................................... 2-8 Error Handle.................................................................................................................................. 2-8 Service Context and Associated Handles.................................................................................. 2-8 Statement Handle, Bind Handle, and Define Handle ........................................................... 2-10 Describe Handle.......................................................................................................................... 2-10 Complex Object Retrieval Handle............................................................................................ 2-10 Security Handle........................................................................................................................... 2-10 Handle Attributes ....................................................................................................................... 2-11 User Memory Allocation ........................................................................................................... 2-12 Descriptors and Locators ................................................................................................................. 2-12 Snapshot Descriptor ................................................................................................................... 2-13 LOB/FILE Datatype Locator..................................................................................................... 2-13 Parameter Descriptor ................................................................................................................. 2-14 ROWID Descriptor ..................................................................................................................... 2-15 Complex Object Descriptor ....................................................................................................... 2-15 Advanced Queueing Descriptors ............................................................................................