Oracle Rdb7™ Guide to SQL Programming Release 7.0 Part No. A42867-1 ® Guide to SQL Programming Release 7.0 Part No. A42867-1 Copyright © 1994, 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 is a registered trademark of Oracle Corporation, Redwood City, California. Oracle CDD/Repository, Oracle Rally, Oracle Rdb, and Rdb7 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 ........................................... xix Preface ........................................................... xxi Technical Changes and New Features ............................... xxv Part I SQL Programming Overview 1 Introduction to SQL Programming 1.1 What Are the Two SQL Programming Interfaces? . ................ 1–1 1.1.1 SQL Module Processor . ................................. 1–2 1.1.2 SQL Precompiler ........................................ 1–3 1.2 Choosing a Programming Interface ............................. 1–3 1.3 Finding Online Program Examples ............................. 1–5 Part II Developing Application Programs That Use SQL 2 SQL Program Development Cycle 2.1 Overview of the Application Program Development Cycle ............ 2–1 2.2 Understanding End-User Requirements ......................... 2–2 2.3 Investigating Metadata and Data .............................. 2–3 2.4 Developing a Prototype ...................................... 2–4 2.5 Converting the Prototype to an Application Program ................ 2–5 2.6 Developing an Application Program ............................. 2–6 iii 3 Introduction to SQL Module Language 3.1 Developing SQL Module Language Application Programs: Basic Steps .................................................... 3–1 3.2 Creating an SQL Module Source File ............................ 3–3 3.2.1 Including Blank Lines and Comments in an SQL Module ......... 3–6 3.2.2 Naming a Module . ...................................... 3–6 3.2.3 Specifying the Dialect .................................... 3–7 3.2.4 Specifying Character Sets for a Session . ...................... 3–8 3.2.5 Identifying the Host Language That Calls Module Procedures ..... 3–8 3.2.6 Specifying the Catalog .................................... 3–9 3.2.7 Specifying the Schema .................................... 3–10 3.2.8 Specifying an Authorization Identifier . ...................... 3–10 3.2.9 Specifying the Alias ...................................... 3–11 3.2.10 Specifying That Parameters Must Include Colons . ............. 3–11 3.2.11 Specifying DECLARE Statements in Modules .................. 3–12 3.3 Calling SQL Module Procedures from a Host Language Program . ..... 3–13 3.4 Writing Portable Applications Using the SQL Module Processor . ..... 3–15 3.5 Finding More Information About the SQL Module Processor .......... 3–15 4 Writing Module SQL Procedures 4.1 Introducing SQL Module Procedures ............................ 4–1 4.2 Specifying the Common Elements of SQL Module Procedures ......... 4–3 4.2.1 Naming a Procedure ..................................... 4–3 4.2.2 Declaring Procedure Parameters ............................ 4–4 4.2.3 Parameters Required for Different Kinds of Procedures .......... 4–5 4.2.4 Associating Procedure Parameters and Actual Parameters . ..... 4–9 4.2.5 Specifying Parameter Data Types ........................... 4–11 4.2.6 Effect of the LANGUAGE Clause on the Parameter Data Type ..... 4–12 4.2.7 Effect of the LANGUAGE Clause on the Parameter-Passing Mechanism ............................................. 4–13 4.2.8 Overriding the Default Passing Mechanism for a Procedure Parameter ............................................. 4–15 4.2.9 Requesting a Run-Time Check of Parameters Used by the Calling Module . .............................................. 4–15 4.3 Using Single SQL Statements in Procedures ...................... 4–16 4.4 Using Compound Statements in Multistatement Procedures .......... 4–16 4.5 Understanding the Restrictions of the SQL Module Language . ..... 4–18 iv 5 Processing SQL Modules and Host Language Files 5.1 Invoking the SQL Module Processor . ......................... 5–1 5.2 Processing SQL and Host Language Modules ..................... 5–2 5.3 Bypassing Parameter Checking for Faster Compilation .............. 5–4 5.4 Improving SQL Module Processor Performance for Remote Databases ................................................ 5–4 5.5 Using Context Files with SQL Module Language . ................ 5–5 5.6 Deciding on the Scope of an SQL Module ......................... 5–6 6 Using Precompiled SQL 6.1 Understanding the Precompiler Process . ......................... 6–1 6.2 Embedding SQL Statements in Host Programs .................... 6–4 6.3 Invoking the Precompiler ..................................... 6–7 6.4 Finding Precompile-Time and Compile-Time Errors ................ 6–11 6.5 Improving Precompiler Performance for Remote Databases . ........ 6–12 6.6 Specifying Compile-Time and Run-Time Options . ................ 6–12 6.6.1 Using the DECLARE MODULE Statement .................... 6–13 6.6.2 Including Declarations in an SQL Context File . ................ 6–14 6.7 Language-Specific Guidelines for Using the SQL Precompiler . ........ 6–15 6.7.1 Embedding SQL Statements in Ada Source Files ............... 6–15 6.7.2 Precompiling Ada Programs ................................ 6–16 6.7.3 Embedding SQL Statements in C Source Files . ................ 6–18 6.7.4 Embedding SQL Statements in COBOL Source Files ............ 6–19 6.7.5 Embedding SQL Statements in FORTRAN Source Files . ........ 6–22 6.7.6 Embedding SQL Statements in Pascal Source Files .............. 6–25 6.7.7 Embedding SQL Statements in PL/I Source Files ............... 6–26 7 Creating Images for Program Execution 7.1 Understanding Executable and Shareable Images . ................ 7–2 7.2 Using the OpenVMS Linker . ................................. 7–2 7.2.1 Linking Programs Compiled with the Digital C Compiler on OpenVMS VAX Systems . ................................. 7–3 7.2.2 Creating an Executable Image That Links with a Shareable Image ................................................. 7–4 7.2.3 Linking Ada Objects ...................................... 7–4 7.3 Creating Shareable Images . ................................. 7–6 7.3.1 Creating Executable and Shareable Images Not Sharing Database Attaches ............................................... 7–7 7.3.2 Creating Executable and Shareable Images Sharing Database Attaches ............................................... 7–8 v 7.4 Installing Shareable Images .................................. 7–11 7.5 Linking Modules on Digital UNIX .............................. 7–12 7.5.1 Building Applications with Multiple Modules .................. 7–13 7.6 Inserting Precompiled SQL Modules in Object Libraries and Archives .................................................. 7–13 7.7 Running a Program . ...................................... 7–14 7.8 Debugging SQL Statements and Program Code .................... 7–14 8 Declaring and Using Parameters 8.1 Overview of Declaring and Using Parameters ..................... 8–1 8.2 Understanding Terminology ................................... 8–3 8.3 Understanding Parameter Function and Declaration Options ......... 8–3 8.4 Declaring the Data Types of Parameters . ...................... 8–6 8.5 Copying Parameter Declarations from a Source Outside Your Program .................................................. 8–9 8.6 Using the SQL INCLUDE Statement ........................... 8–9 8.6.1 Using the SQL INCLUDE FROM DICTIONARY Statement . ..... 8–10 8.6.2 Using the INCLUDE SQLCA Statement ...................... 8–11 8.6.3 Using the INCLUDE SQLDA or SQLDA2 Statement ............ 8–12 8.6.4 Using the INCLUDE File Statement . ...................... 8–12 8.7 Using the SQL Module Language FROM path-name Clause .......... 8–13 8.8 Using Host Language COPY or INCLUDE Statements . ............