InterBase 6 Embedded SQL Guide Borland/INPRISE 100 Enterprise Way, Scotts Valley, CA 95066 http://www.interbase.com November 12, 1999 (C:\TechPubs60\60DocSet\Doc\EmbedSQL\EmbedSQLTitle.fm5) Inprise/Borland may have patents and/or pending patent applications covering subject matter in this document. The furnishing of this document does not convey any license to these patents. Copyright 1999 Inprise/Borland. All rights reserved. All InterBase products are trademarks or registered trademarks of Inprise/Borland. All Borland products are trademarks or registered trademarks of Inprise/Borland. Other brand and product names are trademarks or registered trademarks of their respective holders. 1INT0055WW21000 6E1R0699 Table of Contents List of Tables.....................................xi List of Figures.................................... xiii List of Examples....................................xv CHAPTER 1 Using the Embedded SQL Guide Who should use this guide .....................17 Topics covered in this guide ....................18 Sample database and applications .................19 CHAPTER 2 Application Requirements Requirements for all applications .................21 Porting considerations for SQL................ 22 Porting considerations for DSQL ............... 22 Declaring host variables.................... 22 Declaring and initializing databases ................25 Using SET DATABASE ..................... 26 Using CONNECT ........................ 27 Working with a single database ............... 27 SQL statements ............................28 Error handling and recovery ....................28 Closing transactions .........................28 Accepting changes ....................... 29 Undoing changes ........................ 29 Closing databases ..........................30 DSQL requirements .........................30 Declaring an XSQLDA ..................... 31 DSQL limitations ...........................32 Using database handles .................... 32 Using the active database ................... 33 Using transaction names ................... 33 Preprocessing programs ......................34 EMBEDDED SQL GUIDE iii CHAPTER 3 Working with Databases Declaring a database ........................35 Declaring multiple databases ................. 37 Preprocessing and run time databases ........... 38 Controlling SET DATABASE scope ............... 39 Specifying a connection character set ...............40 Opening a database .........................41 Using simple CONNECT statements.............. 41 Additional CONNECT syntax.................. 45 Attaching to multiple databases ............... 46 Handling CONNECT errors .................. 46 Setting database cache buffers ................ 47 Accessing an open database ....................48 Differentiating table names .....................49 Closing a database ..........................49 With DISCONNECT ....................... 50 With COMMIT and ROLLBACK ................. 50 CHAPTER 4 Working with Transactions Starting the default transaction ..................55 Starting without SET TRANSACTION ............. 55 Starting with SET TRANSACTION ............... 56 Starting a named transaction ....................57 Naming transactions ...................... 58 Specifying SET TRANSACTION behavior ........... 60 Using transaction names in data statements ...........72 Ending a transaction ........................74 Using COMMIT ......................... 75 Using ROLLBACK ........................ 78 Working with multiple transactions ................79 The default transaction .................... 80 Using cursors .......................... 80 A multi-transaction example ................. 81 Working with multiple transactions in DSQL ...........83 iv INTERBASE 6 TABLE OF CONTENTS Modifying transaction behavior with “?”........... 83 CHAPTER 5 Working with Data Definition Statements Creating metadata ..........................88 Creating a database ...................... 89 Creating a domain ....................... 90 Creating a table......................... 91 Creating a view ......................... 94 Creating an index ....................... 96 Creating generators ...................... 98 Dropping metadata .........................98 Dropping an index ....................... 99 Dropping a view ........................ 99 Dropping a table ....................... 100 Altering metadata ......................... 100 Altering a table ........................ 101 Altering a view ........................ 105 Altering an index....................... 105 CHAPTER 6 Working with Data Supported datatypes ........................ 108 Understanding SQL expressions ................. 110 Using the string operator in expressions ......... 112 Using arithmetic operators in expressions ........ 113 Using logical operators in expressions .......... 113 Using comparison operators in expressions ....... 114 Determining precedence of operators ........... 122 Using CAST( ) for datatype conversions .......... 125 Using UPPER() on text data ................. 125 Understanding data retrieval with SELECT ........... 126 Listing columns to retrieve with SELECT.......... 128 Specifying host variables with INTO ............ 131 Listing tables to search with FROM............. 132 Restricting row retrieval with WHERE ........... 134 EMBEDDED SQL GUIDE v Sorting rows with ORDER BY ................ 138 Grouping rows with GROUP BY............... 139 Restricting grouped rows with HAVING .......... 140 Appending tables with UNION ............... 141 Specifying a query plan with PLAN............. 142 Selecting a single row ....................... 143 Selecting multiple rows ...................... 144 Declaring a cursor ...................... 145 Opening a cursor....................... 146 Fetching rows with a cursor ................ 147 Closing the cursor ...................... 149 A complete cursor example ................. 149 Selecting rows with NULL values .............. 151 Selecting rows through a view ............... 152 Selecting multiple rows in DSQL ................. 152 Declaring a DSQL cursor .................. 153 Opening a DSQL cursor ................... 154 Fetching rows with a DSQL cursor ............. 154 Joining tables ............................ 155 Choosing join columns ................... 156 Using inner joins ....................... 156 Using outer joins ....................... 159 Using nested joins ...................... 161 Using subqueries .......................... 161 Simple subqueries ...................... 162 Correlated subqueries .................... 163 Inserting data ........................... 164 Using VALUES to insert columns .............. 164 Using SELECT to insert columns .............. 165 Inserting rows with NULL column values ......... 166 Inserting data through a view ............... 169 Specifying transaction names in an INSERT ........ 169 Updating data ........................... 170 vi INTERBASE 6 TABLE OF CONTENTS Updating multiple rows ................... 171 NULLing columns with UPDATE ............... 174 Updating through a view .................. 174 Specifying transaction names in UPDATE ......... 175 Deleting data ............................ 176 Deleting multiple rows ................... 177 Deleting through a view................... 180 Specifying transaction names in a DELETE ........ 180 CHAPTER 7 Working with Dates Selecting dates and times ..................... 184 Inserting dates and times ..................... 185 Updating dates and times ..................... 186 Using CAST( ) to convert dates and times ............ 186 Casting from SQL datatypes to datetime datatypes.... 187 Casting from datetime datatypes to other SQL datatypes 188 Using date literals ......................... 189 CHAPTER 8 Working with Blob Data What is a Blob? ........................... 191 How are Blob data stored? .................... 192 Blob subtypes......................... 193 Blob database storage .................... 194 Blob segment length ..................... 195 Overriding segment length ................. 196 Accessing Blob data with SQL .................. 196 Selecting Blob data ..................... 196 Inserting Blob data ..................... 199 Updating Blob data ..................... 200 Deleting Blob data ...................... 201 Accessing Blob data with API calls ............... 202 Filtering Blob data ......................... 203 Using the standard InterBase text filters ......... 203 Using an external Blob filter ................ 203 EMBEDDED SQL GUIDE vii Writing an external Blob filter .................. 205 Filter types .......................... 206 Read-only and write-only filters .............. 206 Defining the filter function ................. 206 CHAPTER 9 Using Arrays Creating arrays ........................... 216 Multi-dimensional arrays .................. 216 Specifying subscript ranges ................. 217 Accessing arrays .......................... 218 Selecting data from an array ................ 218 Inserting data into an array................. 219 Selecting from an array slice ................ 220 Updating data in an array slice ............... 222 Testing a value in a search condition ........... 223 Using host variables in array subscripts.......... 224 Using arithmetic expressions with arrays ......... 224 CHAPTER 10 Working with Stored Procedures Using stored procedures ..................... 226 Procedures and transactions ................ 226 Security for procedures ................... 227 Using select procedures .....................