Oracle Rdb7™ Guide to Using the Oracle SQL/Services™ Client API
Total Page:16
File Type:pdf, Size:1020Kb
Oracle Rdb7™ Guide to Using the Oracle SQL/Services™ Client API Release 7.0 Part No. A41981-1 ® Guide to Using the Oracle SQL/Services Client API Release 7.0 Part No. A41981-1 Copyright © 1993, 1996, Oracle Corporation. All rights reserved. This software contains proprietary information of Oracle Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software 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. 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. 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, 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. Oracle, Secure Network Services, and SQL*Net are registered trademarks of Oracle Corporation, Redwood City, California. Rdb7, Oracle Rdb, Oracle Trace, and Oracle SQL/Services are trademarks of Oracle Corporation, Redwood City, California. All other company or product names are used for identification purposes only, and may be trademarks of their respective owners. Contents Send Us Your Comments ........................................... ix Preface ........................................................... xi Technical Changes and New Features ............................... xv 1 Overview 1.1 Introduction to Oracle SQL/Services . ......................... 1–2 1.1.1 Client Components ....................................... 1–3 1.1.2 Network Components ..................................... 1–4 1.1.3 Server System Components ................................ 1–5 1.2 Supported Client Platforms . ................................. 1–5 1.3 Preparing Programmers to Use Oracle SQL/Services ................ 1–8 1.3.1 What Programmers Must Know to Write Applications ............ 1–8 1.3.2 Reading Path for Programmers ............................. 1–9 1.4 Location of Oracle SQL/Services Error Documentation .............. 1–9 1.5 What System Managers Must Know to Support Oracle SQL/Services . 1–10 2 Developing Oracle SQL/Services Applications 2.1 Introduction to the Dynamic SQL Interface of Oracle Rdb ............ 2–2 2.2 Overview of Dynamic SQL Interface Statements . ................ 2–2 2.2.1 Execution Statements . ................................. 2–2 2.2.2 Result Table Statements . ................................. 2–3 2.3 Using the Dynamic SQL Interface of Oracle Rdb . ................ 2–4 2.3.1 Parameter Markers ...................................... 2–6 2.3.2 Select List Items ........................................ 2–7 2.3.3 Unknown Statements ..................................... 2–7 2.3.4 SQL Descriptor Area (SQLDA or SQLDA2) .................... 2–7 2.3.5 SQL Communications Area (SQLCA) ......................... 2–8 2.4 Overview of Client API Routines ............................... 2–9 iii 2.4.1 Association Routines ..................................... 2–9 2.4.2 SQL Statement Routines .................................. 2–9 2.4.3 Result Table Routines .................................... 2–10 2.4.4 Utility Routines . ...................................... 2–11 2.4.5 Functional Interface Routines .............................. 2–11 2.5 Overview of Data Structures .................................. 2–13 2.6 Developing Applications with the Functional Interface Routines . ..... 2–14 2.7 Building Oracle SQL/Services Application Programs . ............. 2–14 2.7.1 Building Applications on the OpenVMS Operating System . ..... 2–15 2.7.2 Building Applications on the MS Windows Operating System . ..... 2–15 2.7.2.1 Building 16-Bit Applications on MS Windows V3.1 ........... 2–16 2.7.2.2 Building 32-Bit Applications for Windows 95, Windows NT X86, or Windows NT Alpha . .............................. 2–16 2.7.3 Building Applications on the Digital UNIX Operating System . ..... 2–17 2.7.4 Building Applications on the Macintosh Operating System . ..... 2–17 2.7.4.1 Building Applications on the Macintosh Operating System for MPW.............................................. 2–17 2.7.4.2 Building Applications on the Macintosh Operating System for THINK C ........................................... 2–18 2.7.5 Building Applications on the Solaris Operating Systems .......... 2–19 3 Sample Application Guidelines 3.1 Sample Application . ...................................... 3–1 3.2 Building the Sample Application . .............................. 3–2 3.2.1 Building the Sample Application on the OpenVMS Operating System . .............................................. 3–2 3.2.2 Building the Sample Application on MS Windows V3.1 ........... 3–2 3.2.3 Building the Sample Application on Windows NT X86, Windows NT Alpha, or Windows 95 .................................... 3–3 3.2.4 Building the Sample Application on the Digital UNIX Operating System . .............................................. 3–3 3.2.5 Building the Sample Application on the Macintosh Operating System . .............................................. 3–4 3.2.5.1 Building the Sample Application in the MPW Programming Environment . ...................................... 3–4 3.2.5.2 Building the Sample Application in the THINK C Programming Environment . ...................................... 3–4 3.2.6 Building the Sample Application on the Solaris Operating System . .............................................. 3–5 3.3 Running the Sample Application . .............................. 3–5 3.4 Driver Module ............................................. 3–7 3.5 Dynamic Module ........................................... 3–7 iv 3.5.1 Creating an Association . ................................. 3–7 3.5.2 Processing the Dynamic SQL Statement ...................... 3–10 3.5.2.1 Declaring and Allocating SQLDA_ID Identifiers ............. 3–12 3.5.2.2 Executing SQL Statements Using the sqlsrv_execute_immediate API Routine ......................................... 3–13 3.5.2.3 Preparing the SQL Statement . ......................... 3–13 3.5.2.4 Allocating Data and Indicator Variables . ................ 3–14 3.5.2.5 Processing Parameter Markers . ......................... 3–15 3.5.2.6 Testing for SELECT Statements ......................... 3–19 3.5.2.7 Processing a SELECT Statement ......................... 3–19 3.5.2.8 Processing Executable Statements ........................ 3–20 3.5.2.9 Processing Select List Items . ......................... 3–20 3.5.2.10 Error Handling ...................................... 3–24 3.5.2.11 Releasing Prepared Statements . ......................... 3–26 4 Performance Considerations 4.1 Batched Execution . ......................................... 4–1 4.2 Improving Row Fetch Performance ............................. 4–3 4.3 Using Stored Procedures and Compound Statements ............... 4–7 4.4 Reusing SQL Statements ..................................... 4–8 5 Logging for Performance and Debugging 5.1 Enabling and Disabling Logging ............................... 5–1 5.2 Association Logging ......................................... 5–3 5.3 Routine Logging . ......................................... 5–4 5.4 Message Protocol Logging . ................................. 5–6 6 API Routines 6.1 Documentation Format ...................................... 6–1 6.1.1 Routine Name . ......................................... 6–1 6.1.2 Return Values . ......................................... 6–2 6.1.3 C Format Section ........................................ 6–2 6.2 Oracle SQL/Services Data Types ............................... 6–2 6.3 API Routines .............................................. 6–3 6.3.1 Association Routines ..................................... 6–4 sqlsrv_abort ............................................... 6–5 sqlsrv_associate . ......................................... 6–6 sqlsrv_get_associate_info ..................................... 6–13 sqlsrv_release .............................................. 6–16 v 6.3.2 SQL Statement Routines .................................. 6–18 sqlsrv_prepare ............................................. 6–19 sqlsrv_execute_in_out . ...................................... 6–23 sqlsrv_execute_immediate .................................... 6–28 sqlsrv_release_statement ..................................... 6–30 6.3.3 Result Table Routines .................................... 6–32 sqlsrv_declare_cursor . ...................................... 6–33 sqlsrv_open_cursor .......................................... 6–36 sqlsrv_fetch . .............................................. 6–39 sqlsrv_fetch_many .........................................