Teradata Database. SQL Reference. Stored Procedures and Embedded SQL

Transcription

1 Teradata Database SQL Reference Stored Procedures and Embedded SQL Release V2R6.2 B A September 2006

2 The product described in this book is a licensed product of Teradata, a division of NCR Corporation. NCR, Teradata and BYNET are registered trademarks of NCR Corporation. Adaptec and SCSISelect are registered trademarks of Adaptec, Inc. EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. Engenio is a trademark of Engenio Information Technologies, Inc. Ethernet is a trademark of Xerox Corporation. GoldenGate is a trademark of GoldenGate Software, Inc. Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. IBM, CICS, DB2, MVS, RACF, OS/390, Tivoli, and VM are registered trademarks of International Business Machines Corporation. Intel, Pentium, and XEON are registered trademarks of Intel Corporation. KBMS is a registered trademark of Trinzic Corporation. Linux is a registered trademark of Linus Torvalds. LSI, SYM, and SYMplicity are registered trademarks of LSI Logic Corporation. Active Directory, Microsoft, Windows, Windows Server, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Novell is a registered trademark of Novell, Inc., in the United States and other countries. SUSE is a trademark of SUSE LINUX Products GmbH, a Novell business. QLogic and SANbox are registered trademarks of QLogic Corporation. SAS and SAS/C are registered trademark of SAS Institute Inc. Sun Microsystems, Sun Java, Solaris, SPARC, and Sun are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. or other countries. Unicode is a registered trademark of Unicode, Inc. UNIX is a registered trademark of The Open Group in the US and other countries. NetVault is a trademark and BakBone is a registered trademark of BakBone Software, Inc. NetBackup and VERITAS are trademarks of VERITAS Software Corporation. Other product and company names mentioned herein may be the trademarks of their respective owners. THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN AS-IS BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON- INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL NCR CORPORATION (NCR) BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. The information contained in this document may contain references or cross references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that NCR intends to announce such features, functions, products, or services in your country. Please consult your local NCR representative for those features, functions, products, or services available in your country. Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. NCR may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please teradata-books@lists.ncr.com Any comments or materials (collectively referred to as Feedback ) sent to NCR will be deemed non-confidential. NCR will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, NCR will be free to use any ideas, concepts, know-how or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback. Copyright by NCR Corporation. All Rights Reserved.

3 Preface Purpose SQL Reference: Stored Procedures and Embedded SQL describes how to create server and client applications using SQL to manipulate data. This book should be used in conjunction with the other volumes of Teradata Database SQL Reference. Audience Application programmers are the principal audience for this book. System administrators, database administrators, security administrators, NCR field engineers, and other technical personnel responsible for designing, maintaining, and using the Teradata database might also find this manual to be useful. Supported Software Release This book supports Teradata Database Release V2R6.2. Prerequisites If you are not familiar with the Teradata database management system, you should read Introduction to the Teradata Database before reading this book. More information about developing applications using embedded SQL is found in Teradata Preprocessor2 for Embedded SQL Programmer Guide. You should be familiar with basic relational database management technology. This book is not an SQL primer. SQL Reference: Stored Procedures and Embedded SQL iii

4 Preface Changes to This Book Changes to This Book This book includes the following changes to support the current release: Date Description September, 2006 Updated Chapter 7 for the BIGINT data type. Added WITH COUNT clause to EXEC SQL statement prefix in Chapter 8 to support parameter arrays. Added SQLDA host data type codes for BIGINT data type to Appendix B. Added complete SQLDA host data type encodings in Appendix B for IN, INOUT, and OUT stored procedure parameter types. Also corrected several erroneous nullable and non-nullable encodings. November 2005 Updated descriptions of FETCH and SELECT INTO for UDTs in stored procedures. Updated descriptions of stored procedure parameters, local variables, and expressions for UDTs. Updated stored procedure SET statement for UDT expressions. Updated lists of supported and unsupported DDL statements in stored procedures. Added restriction explaining that embedded SQL does not generally support UDTs (with documented exceptions and workarounds) to the introductions of chapters 1, 2, 7, 8, and 9. Updated description of ACTIVITY_COUNT to account for overflow when an activity count greater than 2 32 is returned. Reformatted and updated several tables in appendixes B, C, D, and E. November 2004 Updated book for V2R6.0 features, including Stored procedure support for Large Objects (LOBs) and triggers New stored procedure lexicon (a COLON character prefixing a local variable is now optional) Support for external stored procedures Support for queue tables Support for recursive query iv SQL Reference: Stored Procedures and Embedded SQL

5 Preface Additional Information Additional Information Additional information that supports this product and the Teradata Database is available at the following Web sites. Type of Information Description Source Overview of the release Information too late for the manuals Additional information related to this product CD-ROM images Ordering information for manuals General information about Teradata The Release Definition provides the following information: Overview of all the products in the release Information received too late to be included in the manuals Operating systems and Teradata Database versions that are certified to work with each product Version numbers of each product and the documentation for each product Information about available training and support center Use the NCR Information Products Publishing Library site to view or download the most recent versions of all manuals. Specific manuals that supply related or additional information to this manual are listed. This site contains a link to a downloadable CD-ROM image of all customer documentation for this release. Customers are authorized to create CD-ROMs for their use from this image. Use the NCR Information Products Publishing Library site to order printed versions of manuals. The Teradata home page provides links to numerous sources of information about Teradata. Links include: Executive reports, case studies of customer experiences with Teradata, and thought leadership Technical information, solutions, and expert advice Press releases, mentions and media resources Click General Search. In the Publication Product ID field, enter 1725 and click Search to bring up the following Release Definition: Base System Release Definition B K Click General Search, and do one of the following: In the Product Line field, select Software - Teradata Database for a list of all of the publications for this release, In the Publication Product ID field, enter a book number: Click General Search. In the Title or Keyword field, enter CD-ROM, and click Search. Click How to Order under Print & CD Publications. Teradata.com SQL Reference: Stored Procedures and Embedded SQL v

6 Preface References to Microsoft Windows References to Microsoft Windows This book refers to Microsoft Windows. For Teradata Database V2R6.2, such references mean Microsoft Windows Server bit and Microsoft Windows Server bit. vi SQL Reference: Stored Procedures and Embedded SQL

7 Table of Contents Preface iii Purpose iii Audience iii Supported Software Release iii Prerequisites iii Changes to This Book iv Additional Information v References to Microsoft Windows vi SECTION 1 Constructs Common to Stored Procedures and Embedded SQL Chapter 1: SQL Cursors Cursors Cursors and Embedded SQL Transactions and Cursors Positioned Cursors Features Supporting Positioned Cursors Rules for Using Positioned Cursors Usage Guidelines for Positioned Cursors SQL Reference: Stored Procedures and Embedded SQL vii

8 Table of Contents Chapter 2: SQL Cursor Control and DML Statements CLOSE DECLARE CURSOR DECLARE CURSOR (Dynamic SQL Form) DECLARE CURSOR (Macro Form) DECLARE CURSOR (Request Form) DECLARE CURSOR (Selection Form) DECLARE CURSOR (Stored Procedures Form) DELETE (Positioned Form) FETCH (Embedded SQL Form) FETCH (Stored Procedures Form) OPEN (Embedded SQL Form) OPEN (Stored Procedures Form) POSITION REWIND SELECT AND CONSUME INTO SELECT INTO UPDATE (Positioned Form) Chapter 3: Result Code Variables SQLSTATE SQLCODE ACTIVITY_COUNT viii SQL Reference: Stored Procedures and Embedded SQL

9 Table of Contents SECTION 2 SQL Stored Procedures Chapter 4: SQL Stored Procedures Stored Procedure Overview DDL Statements for Stored Procedure Objects Granting Privileges on Stored Procedures Performing a Stored Procedure Restrictions on Stored Procedures Stored Procedure Lexicon Supported DDL Statements in Stored Procedures Unsupported DDL Statements in Stored Procedures Supported DML Statements in Stored Procedures Supported DCL Statements in Stored Procedures SQL Operations on Stored Procedures Control Statements in Stored Procedures Completion Condition and Exception Condition Handlers Cursor Declarations Rules for Using SQL Statements in Stored Procedures Using Dynamic SQL in Stored Procedures Recursive Stored Procedures Archiving and Restoring Stored Procedures Stored Procedures and Tactical Queries Debugging Stored Procedures Sample Stored Procedure SQL Reference: Stored Procedures and Embedded SQL ix

10 Table of Contents Chapter 5: SQL Control Statements BEGIN END CASE DECLARE FOR IF ITERATE LEAVE LOOP REPEAT SET WHILE Chapter 6: Condition Handling Condition Handling: Overview Statement-Specific Condition Handling DECLARE HANDLER (Basic Syntax) DECLARE HANDLER (CONTINUE Type) DECLARE HANDLER (EXIT Type) DECLARE HANDLER (SQLEXCEPTION Type) DECLARE HANDLER (SQLWARNING Type) DECLARE HANDLER (NOT FOUND Type) x SQL Reference: Stored Procedures and Embedded SQL

11 Table of Contents SECTION 3 Embedded SQL Chapter 7: Embedded SQL Embedded SQL Host Structures Host Variables Input Host Variables Output Host Variables SQL Character Strings as Host Variables Indicator Variables Multistatement Requests With Embedded SQL Chapter 8: Static Embedded SQL Statements BEGIN DECLARE SECTION COMMENT (Returning Form) DATABASE DECLARE STATEMENT DECLARE TABLE END DECLARE SECTION END-EXEC Statement Terminator EXEC EXEC SQL Statement Prefix INCLUDE INCLUDE SQLCA INCLUDE SQLDA WHENEVER SQL Reference: Stored Procedures and Embedded SQL xi

12 Table of Contents Chapter 9: Dynamic Embedded SQL Statements Using Dynamic SQL Performing SQL Statements Dynamically Dynamic SQL Statement Syntax DESCRIBE EXECUTE (Dynamic SQL Form) EXECUTE IMMEDIATE PREPARE Chapter 10: Client-Server Connectivity Statements Connecting a Client Application to the Teradata Database CONNECT GET CRASH LOGOFF LOGON SET BUFFERSIZE SET CHARSET SET CONNECTION SET CRASH SET ENCRYPTION Chapter 11: Multisession Asynchronous Programming With Embedded SQL Multisession Programming With Embedded SQL Embedded SQL Statements Supporting Multisession Asynchronous Request Programming ASYNC Statement Modifier TEST WAIT xii SQL Reference: Stored Procedures and Embedded SQL

13 Table of Contents SECTION 4 Appendixes Appendix A: Notation Conventions Syntax Diagram Conventions Character Shorthand Notation Used In This Book Predicate Calculus Notation Used in This Book Appendix B: SQL Descriptor Area (SQLDA) The SQL Descriptor Area SQLDA Structure SQLDA Data Type Codes Appendix C: SQL Communications Area (SQLCA) The SQL Communications Area SQLCA Fields Mapping SQLCODE Values to Teradata Database Error Message Numbers Mapping SQLCODE Values to SQLSTATE Values Mapping SQLCODE Values to SQLSTATE Values Appendix D: SQLSTATE Mappings SQLSTATE Codes Mapping Teradata Database Error Messages to SQLSTATE Values SQL Reference: Stored Procedures and Embedded SQL xiii

14 Table of Contents Appendix E: SQLCODE Diagnostic Handling Diagnostic Handling Mapped SQLCODE to Teradata Database Code Mapped SQLCODE to SQLSTATE Mapped Teradata Database Code to SQLSTATE Mapped CLI Code to SQLSTATE Mapped CLI Code to SQLCODE Glossary Index xiv SQL Reference: Stored Procedures and Embedded SQL

15 SECTION 1 Constructs Common to Stored Procedures and Embedded SQL SQL Reference: Stored Procedures and Embedded SQL 1

16 Section 1: Constructs Common to Stored Procedures and Embedded SQL 2 SQL Reference: Stored Procedures and Embedded SQL

17 CHAPTER 1 SQL Cursors This chapter describes SQL cursors: what they are, when they are used, and how they are used to point to rows in an SQL response set. The following specific topics are described in this chapter: Cursors on page 2 Cursors and Stored Procedures on page 5 Cursors and Embedded SQL on page 7 Transactions and Cursors on page 10 Positioned Cursors on page 12 Features Supporting Positioned Cursors on page 14 Rules for Using Positioned Cursors on page 16 Usage Guidelines for Positioned Cursors on page 18 Note that UDTs are not specifically supported for embedded SQL. However, UDTs for which tosql and fromsql transforms have been defined can be externally referenced by means of their transform target data types. 1 As a result, embedded SQL applications can use SQL statements that reference UDTs provided that the UDTs have a defined tosql or fromsql transform as appropriate. Additionally, the application must send and receive UDT data in the form of its external (non-udt) data type. 1. You must have, at minimum, the UDTUSAGE privilege on any UDT columns you access from an application. SQL Reference: Stored Procedures and Embedded SQL 1

18 Chapter 1: SQL Cursors Cursors Cursors Definition A cursor is a data structure used at runtime by stored procedures and by Preprocessor2 to point to the result rows in a response set returned by an SQL query. Cursors are only applicable to the following SQL application types: Client applications written in C, COBOL, or PL/I that contain embedded SQL statements and have been precompiled using Preprocessor2 Stored procedures The syntax of functionally similar cursor control statements sometimes varies depending on whether they are used for embedded SQL or for stored procedures. Variant syntax forms are documented with the individual cursor control statements. Several cursor control statements are valid only with embedded SQL. Cursors are not valid for sessions conducted interactively from a terminal using a query manager like BTEQ. Why Cursors Are Necessary An embedded or stored procedure SQL SELECT statement is permitted to retrieve at most one row of data at a time. It is an error for a SELECT statement to retrieve more than one row of data in these applications. Without knowing the number of rows to be retrieved from a request, it is impossible to know the number of host variables required to hold the results of the SELECT. Thus, only a single result row is allowed. This is not a problem for so-called singleton SELECTs, which are SELECT statements that are written in such a way that they return only one row. However, SQL queries frequently return multiple rows in the form of a result table or response set. This situation is one that typical programming languages are not equipped to handle. Record-Oriented Languages vs. Set-Oriented Data Another way of expressing this is to say that traditional programming languages such as COBOL, C, and PL/I are record-oriented, while relational databases and their operators are inherently set-oriented. Because of this mismatch, which is sometimes referred to as an impedance mismatch, some mechanism must be used to enable a record-oriented language to process set-oriented data. This mechanism is the cursor. You can think of a cursor as a pointer to a single data row in a result table. Cursors use SQL statements unique to embedded SQL and stored procedures to step through the result table, which is held in a data structure known as a spool file, one row at a time. 2 SQL Reference: Stored Procedures and Embedded SQL

19 Chapter 1: SQL Cursors Cursors Types of Cursors Cursors can be classified in several different ways: 1 Dynamic 2 Macro 3 Request 4 Selection 5 Stored procedure 6 Positioned (updatable) 7 Non-positioned Important: The first five types refer to ways a cursor can be declared in a DECLARE CURSOR statement. Of these, only stored procedure-type cursors are supported in stored procedures. The last two types refer to ways a cursor can be used to manipulate data. Both are supported in embedded SQL and stored procedures. Cursor States and Positions The state of a cursor at any given time is either open or closed. If open, a cursor can point to a returned row from the result table returned by its associated SELECT. This row is said to be the current row. While the relational model does not support the concept of ordered rows, the mechanism of processing a result set one row at a time, as is performed by non-relational programming languages, necessitates a redefinition for this situation only. An open cursor can be in one of three possible positions: Before a row The cursor is positioned before the first row if the cursor was opened but no rows were fetched. On a row The cursor is on a row following a fetch of the row. When a cursor is pointing at a row, that row is referred to as the current row of the cursor. After the last row in a result set. When there are no further rows in the result set to fetch, the cursor points immediately after the last row in the retrieved set. Cursors are also used to manage inserts, updates, execution of multistatement requests, and SQL macros. SQL Reference: Stored Procedures and Embedded SQL 3

20 Chapter 1: SQL Cursors Cursors How Cursors Are Incremented Cursors are incremented using a FETCH statement as needed to step through the response set rows. Stored procedure cursors have some additional facilities that enable more flexibility than embedded SQL cursors possess. The following bullets list these additional facilities: The FIRST and NEXT options of the FETCH statement and the SCROLL and NO SCROLL options of the DECLARE CURSOR declaration enable cursors to either scroll forward to the next row in the spool or to scroll directly to the first row in the spool. Within a FOR loop, a cursor moves to the next row with each iteration of the loop. 4 SQL Reference: Stored Procedures and Embedded SQL

21 Chapter 1: SQL Cursors Cursors and Stored Procedures Cursors and Stored Procedures Cursor Rules for Stored Procedures The following rules apply to the use of cursors in a stored procedure: No more than 15 cursors can be open at any one time in a given stored procedure. Cursors can be defined in two ways: In a DECLARE CURSOR declaration. In a FOR loop control statement. The scope of a cursor declared with DECLARE CURSOR is the compound statement and its nested compound statements, if any. The scope of column name or its correlation name in a FOR loop cursor is restricted to the body of the FOR statement. Cursor names are constructed from the following list of valid characters: uppercase letters lowercase letters # digits underscores The FOR cursor_name statement opens a cursor for the SELECT statement specified as the cursor specification. For a cursor defined in a FOR loop control statement, open cursor, fetch cursor, and close cursor operations are performed implicitly as part of the execution of the FOR loop. The next row, if it exists, is fetched for an open cursor with each iteration of the FOR statement. For a cursor defined by a DECLARE CURSOR declaration, open cursor, fetch cursor, and close cursor operations must be specified explicitly using OPEN, FETCH, and CLOSE statements. The OPEN cursor_name statement opens a cursor for the SELECT statement specified as the cursor specification. The FOR cursor_name loop control statement implicitly opens a cursor for the SELECT statement specified as the cursor specification. To create a positioned cursor, specify a FOR UPDATE clause in the cursor specification of the DECLARE CURSOR declaration. SQL Reference: Stored Procedures and Embedded SQL 5

22 Chapter 1: SQL Cursors Cursors and Stored Procedures Cursor Support in Stored Procedures Support is somewhat different depending on whether a cursor is opened by a FOR loop statement or by a cursor declared by a DECLARE CURSOR statement: The following dummy iteration statement opens a cursor for the specified cursor. FOR for_loop_variable AS [cursor_name CURSOR FOR] cursor_specification DO statement END FOR; where cursor_specification is a single SELECT statement and statement can be one or more SQL control or DML statements. The FOR statement performs as follows: 1 Fetches one row of data from the result set into the for_loop_variable on each iteration. 2 Increments the cursor on each iteration, fetching the next row of data, if it exists. The WHERE CURRENT OF forms of DELETE and UPDATE perform as follows: DELETE WHERE CURRENT OF cursor_name deletes the currently fetched row from its base table. UPDATE WHERE CURRENT OF cursor_name updates the currently fetched row in its base table. For cursors defined by a DECLARE CURSOR statement, you must submit explicit OPEN cursor_name and FETCH cursor_name statements. For more details on the use of cursors in stored procedures, see FOR on page SQL Reference: Stored Procedures and Embedded SQL

23 Chapter 1: SQL Cursors Cursors and Embedded SQL Cursors and Embedded SQL Cursor Rules for Embedded SQL The following rules apply to the use of cursors in an embedded SQL application program: No more than 16 cursors can be open at any one time in a given application. Whether a cursor can be positioned or not depends on how you set the precompiler directives TRANSACT or -tr, as specified by the following table: IF you precompile the application using this setting for TRANSACT or -tr ANSI BTET THEN its cursors are this type by default positioned not positioned The reason for this is that Teradata SQL does not support the ANSI SQL standard FOR READ ONLY and FOR UPDATE clauses for cursors. Once an application has 16 cursors open, it can only issue one of the following as the next statement: CLOSE COMMIT (if in COMMIT mode) FETCH LOGOFF POSITION REWIND Cursor and dynamic statement identifiers are constructed from the following list of valid characters: uppercase letters lowercase letters # digits underscores SQL Reference: Stored Procedures and Embedded SQL 7

24 Chapter 1: SQL Cursors Cursors and Embedded SQL Cursor and dynamic statement identifiers must begin with a national character and cannot exceed 18 characters. A cursor and dynamic statement identifier cannot be an SQL keyword. For purposes of comparison between identifiers, the case of letters is not significant. The preprocessor accepts statements in uppercase, lowercase or mixed case. To support multibyte character sets, cursor and dynamic statement names can have multibyte characters, and they can be expressed in internal hexadecimal notation. Cursor Support Statements in Preprocessor2 The following list explains how the various SQL statements that support cursors fit into a coherent whole in embedded SQL: DECLARE cursor_name CURSOR FOR data_returning_statement associates a cursor name with a multirow data returning statement. You do not need to use a cursor to process a singleton SELECT. You can then use the following statements to manipulate the declared cursor: OPEN cursor_name performs the request (or requests) defined by the DECLARE CURSOR statement. FETCH cursor_name INTO uses the opened cursor to retrieve successive individual rows from the result set into host variables, using host language statements to increment the cursor based on a WHENEVER statement or on testing the value of status codes returned to SQLCODE or SQLSTATE after each FETCH. DELETE WHERE CURRENT OF cursor_name deletes the currently fetched row from its base table. UPDATE WHERE CURRENT OF cursor_name updates the currently fetched row. POSITION cursor_name moves the cursor either forward or backward to the first row of the specified statement. A REWIND statement specifying the cursor name moves the cursor to the first row of the first (or only) statement of a request. CLOSE cursor_name closes the open cursor_name and terminates the data returning statement specified by the DECLARE CURSOR statement. 8 SQL Reference: Stored Procedures and Embedded SQL

25 Chapter 1: SQL Cursors Cursors and Embedded SQL The following table summarizes the actions taken by cursors and related statements and describes the outcomes of those actions. Action SQL Statement Result Define a statement or request to be associated with a cursor. DECLARE CURSOR Defines the association between a cursor and an SQL data returning statement. Open a cursor. OPEN Performs the SQL data returning statement defined in DECLARE CURSOR. Retrieve the next row in the result table. Move the cursor to the first row of a specific SQL statement. Update a row. Delete a row. FETCH POSITION REWIND UPDATE WHERE CURRENT OF DELETE WHERE CURRENT OF Retrieves a row from the result table. Positions the cursor to the first row of the result table of the named statement. Updates the contents of the current row. Deletes the current row from the table. Close the cursor. CLOSE Terminates the retrieval process. SQL Reference: Stored Procedures and Embedded SQL 9

26 Chapter 1: SQL Cursors Transactions and Cursors Transactions and Cursors SQL Terminating Statements and Cursors The following explains how the various SQL statements that terminate transactions process cursors. COMMIT terminates all open cursors and commits the changes made by the cursors while a transaction was in progress. (ANSI session mode only). ROLLBACK (ANSI and Teradata session modes) or ABORT (Teradata session mode only) terminates all open cursors within the current transaction and discards any changes made by the cursors while the transaction was in progress. END TRANSACTION terminates all open cursors within the current transaction and commits any changes made by the cursors while the transaction was in progress (Teradata session mode only). Cursor Semantics and Transactions The following rules describe cursor semantics with respect to implicit and explicit transactions: With respect to implicit transactions (cursor opened in Teradata session mode only): A FOR CURSOR loop opens the cursor as a holdable cursor and its sensitivity is asensitive. A FOR CURSOR loop also supports transaction control statements. In the case of a DECLARE, OPEN, or FETCH CURSOR, the cursor is holdable and its sensitivity is asensitive. With respect to explicit transaction (cursor opened in Teradata mode or in ANSI session mode): A FOR CURSOR loop opens the cursor as a without hold cursor and its sensitivity is asensitive. This implies that when the transaction is closed, the cursor is closed. If a cursor is asensitive, the visibility of significant changes to SQL data is implementation dependent. A FOR CURSOR loop does not permit a COMMIT, ROLLBACK, or ABORT within the FOR loop. This means that if a commit, rollback, or abort is detected during compile time, an error will be reported and the stored procedure will not be created. If a commit, rollback, or abort is not detected during compile time, at run-time error will be reported. This is a failure in Teradata session mode and, as a result, the transaction and the cursor are closed. If the rollback or abort occurs in a nested call (in Teradata session mode), the nested call is reported as having failed. The failure still applies for a subsequent FETCH CURSOR. In the case of a DECLARE, OPEN, OR FETCH CURSOR, the cursor is without hold and its sensitivity is asensitive. Transaction control statements, however, are executed successfully, but the next FETCH or CLOSE CURSOR causes an error to be reported. 10 SQL Reference: Stored Procedures and Embedded SQL

27 Chapter 1: SQL Cursors Transactions and Cursors Cursor Holdability and Transaction and Session Termination Cursor Sensitivity The following describes cursor holdability with respect to transaction and session termination: A holdable cursor is not closed if that cursor is in an open state at the time the transaction terminates with a COMMIT. A holdable cursor that is in a closed state at the time the transaction terminates remains closed. A holdable cursor is closed no matter what its state if the transaction terminates with a ROLLBACK. A holdable cursor is closed and destroyed when the session in which it was created terminates. A cursor that is without hold is closed when the transaction in which it was created terminates. If a cursor is open and the transaction in which the cursor was opened makes a significant change to data, then whether that change is visible through that cursor before it is closed is determined as follows: If a cursor is asensitive, the visibility of significant changes to data is implementationdependent. If a cursor is insensitive, then significant changes to data are not visible. If a cursor is sensitive, then significant changes to data are visible. SQL Reference: Stored Procedures and Embedded SQL 11

28 Chapter 1: SQL Cursors Positioned Cursors Positioned Cursors Introduction The ANSI SQL standard defines an updatable, or positioned, cursor. This means that an application can define a cursor for a query and then update results rows using the same cursor. The ANSI SQL-2003-standard DELETE and UPDATE statements do not identify a search condition. Instead, they identify a cursor with a row to be updated or deleted. Process Flows for Using a Positioned Cursor to Update or Delete a Row in a Stored Procedure The following stages describe the general process flow for updating or deleting a row using a FOR loop cursor in a stored procedure: 1 Specify a FOR statement with the appropriate cursor specification. 2 Fetch one row with each iteration of the FOR statement. The cursor then points to the next row in the response set. 3 Update or delete the fetched row using the WHERE CURRENT OF clause with an UPDATE or DELETE statement, respectively. 4 Continue the FOR iteration loop until the last row is fetched. 5 Close the cursor by terminating the FOR statement. The following stages describe the general process flow for updating or deleting a row using a DECLARE CURSOR-style cursor in a stored procedure: 1 Specify a DECLARE CURSOR statement with the appropriate cursor specification. 2 Open the cursor by performing an OPEN cursor_name statement. 3 Perform FETCH statements to fetch one row at a time from the response set. The next cursor movement depends on the scrollability option you specify. IF the fetch option specified is FIRST NEXT THEN the cursor moves to the first row in the result set. next row in the result set. 4 Update or delete the fetched row using the WHERE CURRENT OF clause with an UPDATE or DELETE statement, respectively. 5 Close the cursor by performing a CLOSE cursor_name statement. 12 SQL Reference: Stored Procedures and Embedded SQL

29 Chapter 1: SQL Cursors Positioned Cursors Process Flow for Updating a Row Using a Cursor in Preprocessor2 The following stages describe the general process flow for updating a row using a cursor in Preprocessor2: 1 Declare a cursor for a SELECT statement. 2 Open the cursor using an OPEN statement. 3 Retrieve a row using the FETCH statement. 4 Update or delete the fetched row using the WHERE CURRENT OF clause with an UPDATE or DELETE statement, respectively. 5 Close the cursor using a CLOSE statement. Positioned Cursors Not Valid for Consume Mode SELECT Statements in Preprocessor2 Related Topics SELECT AND CONSUME statements in positioned cursors are not valid. When you select a row from a queue table using a SELECT AND CONSUME statement, the system automatically consumes that row (see SQL Reference: Data Definition Statements and SQL Reference: Data Manipulation Statements); therefore, it makes no sense to perform SELECT AND CONSUME statements in positioned cursors because once selected, a consumed row cannot be deleted or updated. This means that any SELECT AND CONSUME statement performed from a positioned cursor fails, even though it does not attempt to delete or update any rows. Because all cursors coded in a Preprocessor2 application default to being positioned cursors when you precompile the code with the TRANSACT or -tr preprocessor directives (see Cursor Rules for Embedded SQL on page 7 and Teradata Preprocessor2 for Embedded SQL Programmer Guide) set to ANSI, this means that you cannot perform SELECT AND CONSUME statements from a cursor in an ANSI-style embedded SQL application. See Teradata Preprocessor2 for Embedded SQL Programmer Guide for examples of implementing updatable cursors in an embedded SQL client application. See FOR on page 155 for examples of implementing updatable cursors in stored procedures. SQL Reference: Stored Procedures and Embedded SQL 13

30 Chapter 1: SQL Cursors Features Supporting Positioned Cursors Features Supporting Positioned Cursors Introduction Several features enable ANSI SQL-2003-standard positioned cursor functionality, including: WHERE CURRENT OF clause in DELETE and UPDATE statements. FOR CHECKSUM clause of the LOCKING modifier (embedded SQL only). FOR UPDATE clause in SELECT statements (stored procedures only). WHERE CURRENT OF Clause FOR CHECKSUM Clause Once a cursor declaration is defined as updatable, the DELETE and UPDATE statements must have some mechanism for acting on the row pointed to by the cursor. The WHERE CURRENT OF clause performs that function. For example, the following DELETE statement deletes the current customer row from the cursor named x01. EXEC SQL DELETE FROM customer WHERE CURRENT OF x01; Updatable cursors do not recognize resource locking levels. Instead, they assume that all actions involving a cursor are done within a single transaction and that terminating that transaction closes any open cursors. To this functionality, the FOR CHECKSUM clause of the LOCKING modifier, a Teradata extension to the ANSI SQL-2003 standard has been added. When no LOCKING modifier is specified, all SELECT statements use a READ level lock. Positioned updates and deletes both default to a WRITE severity row hash lock. The FOR CHECKSUM clause is not supported for stored procedures. How CHECKSUM Locking Works CHECKSUM locking is similar to ACCESS locking, but it adds checksums to the rows of a results table to allow a test of whether a row in the cursor has been modified by another user or session at the time an update is being made through the cursor. If an application specifies an ACCESS lock and then issues a cursor UPDATE or DELETE, the row to be changed might have been altered by another application between the time the first application read the row and the time it issued the cursor UPDATE or DELETE statement. If the checksum changes because another application has updated the row since it was last read by the current application, the current application receives an error. 14 SQL Reference: Stored Procedures and Embedded SQL

31 Chapter 1: SQL Cursors Features Supporting Positioned Cursors An error is returned to the application whenever any of the following requirements for CHECKSUM locking are not met: The object locked must be a table The LOCKING modifier must be followed by an updatable cursor SELECT The table specified in the LOCKING modifier must be the same as the table referenced in the FROM clause of the SELECT statement that follows it CHECKSUM locks are valid only when used with a SELECT statement opened by an updatable cursor. Example: LOCKING with CHECKSUM This example uses checksum locking on the table named t. LOCKING TABLE t FOR CHECKSUM SELECT i, text FROM t; SQL Reference: Stored Procedures and Embedded SQL 15

32 Chapter 1: SQL Cursors Rules for Using Positioned Cursors Rules for Using Positioned Cursors Positioned cursors must observe a specific set of rules that constrain the options of the SELECT statement to which they apply. The rules for defining a positioned cursor are as follows: Positioned UPDATEs and DELETEs must be in the same transaction as the SELECT that opened the cursor they are using. The following items are not updatable: Dynamic cursors Multistatement requests The following items are not allowed in an SQL statement controlled by an updatable cursor: Tables with triggers defined on them Joins between multiple base tables DISTINCT keyword GROUP BY clause HAVING clause WITH clause ORDER BY clause Aggregate operators Set operators Correlated subqueries Select lists having any of the following: duplicate column names expressions functions For positioned cursors in a stored procedure, the Parser determines whether a cursor is updatable or not as follows: IF the SELECT statement specified by a cursor declaration specifies a FOR UPDATE clause does not specify a FOR UPDATE clause THEN the cursor is updatable. not updatable. The SELECT statement is still processed, but the Teradata Database returns a warning message stating that the cursor is not updatable. 16 SQL Reference: Stored Procedures and Embedded SQL

33 Chapter 1: SQL Cursors Rules for Using Positioned Cursors Multiple updates of a currently fetched row or updates followed by a delete of the currently fetched row are allowed. Positioned updates and deletes must occur within the same transaction that contains the SELECT statement that defined the cursor. When the application attempts a positioned UPDATE or DELETE against a row selected by a nonvalid SELECT, the Teradata Database returns an error and rolls back the affected transaction. When a program attempts to UPDATE or DELETE a row using a WHERE CURRENT OF clause for a cursor that is not updatable, the Teradata Database returns an error stating that the cursor is not updatable. FOR stored procedures created under this session mode ANSI Teradata Positioned cursors are valid not valid SQL Reference: Stored Procedures and Embedded SQL 17

34 Chapter 1: SQL Cursors Usage Guidelines for Positioned Cursors Usage Guidelines for Positioned Cursors The following guidelines describe ways to optimize the performance of positioned cursors. Because of the number of row hash locks required to implement cursor updates on large sets of data, you should use positioned updates and deletes for small sets of data only. When too many row hash locks are imposed, the transaction fails and aborts with a lock table overflow error. Either avoid long duration transactions when using updatable cursors or use CHECKSUM locking 2 to avoid locking conflicts that might prevent other applications from reading or updating the tables used by your application. When the number of row hash locks becomes excessive and a lock table overflow error occurs, the Teradata Database issues a transaction level abort for any SQL application that receives the error. Cursor conflicts can occur within a single transaction. Such a conflict occurs when any of the following conditions exist: There are two cursors opened on the same table at the same time within a transaction and one of the cursors attempts a positioned update or delete on a row in the table that is currently the subject of a positioned update or delete request by the other cursor. A cursor is opened on a table, a searched update or delete is made on that table, and then the cursor attempts to perform a positioned update or delete on the table. A cursor is opened on a table, a positioned update or delete is made through the cursor, and then a searched update or delete is attempted on the same table. All three situations return a cursor conflict warning to the user but perform the requested deletion or update. 2. CHECKSUM locking is not supported for stored procedures. 18 SQL Reference: Stored Procedures and Embedded SQL