INFORMIX-OnLine Workgroup Server

Transcription

1 INFORMIX-OnLine Workgroup Server Informix Guide to SQL: Syntax, Volume 2 for UNIX Version 7.12 June 1996 Part No

2 Published by INFORMIX Press Informix Software, Inc Bohannon Drive Menlo Park, CA Copyright by Informix Software, Inc.; provided, portions may be copyright in third parties, as set forth in documentation. All rights reserved. The following are worldwide trademarks of Informix Software, Inc., or its subsidiaries, registered in the United States of America as indicated by, and in numerous other countries worldwide: INFORMIX ; C-ISAM ; INFORMIX -OnLine Dynamic Server The following are worldwide trademarks of the indicated owners or their subsidiaries, registered in the United States of America as indicated by, and in numerous other countries worldwide: Adobe Systems Incorporated: PostScript Regents of the University of California: BSD Microsoft Corporation: Microsoft ; MS ; MS-DOS ; CodeView ; MS Windows ; Windows ; Windows 95; Windows NT ; Windows for Workgroups ; ODBC ; Visual Basic ; Visual C++ Microsoft Memory Management Product: HIMEM.SYS ( DOS as used herein refers to MS-DOS and/or PC-DOS operating systems.) X/Open Company Ltd.: UNIX ; X/Open All other marks or symbols are registered trademarks or trademarks of their respective owners. Documentation Team: Diana Chase, Smita Joshi, Geeta Karmarkar, Patrice O Neill To the extent that this software allows the user to store, display, and otherwise manipulate various forms of data, including, without limitation, multimedia content such as photographs, movies, music and other binary large objects (blobs), use of any single blob may potentially infringe upon numerous different third-party intellectual and/or proprietary rights. It is the user's responsibility to avoid infringements of any such thirdparty rights. RESTRICTED RIGHTS/SPECIAL LICENSE RIGHTS Software and documentation acquired with US Government funds are provided with rights as follows: (1) if for civilian agency use, with Restricted Rights as defined in FAR ; (2) if for Dept. of Defense use, with rights as restricted by vendor's standard license, unless superseded by negotiated vendor license as prescribed in DFAR Any whole or partial reproduction of software or documentation marked with this legend must reproduce the legend. ii Informix Guide to SQL: Syntax

3 Table of Contents Table of Contents Introduction Products Covered in This Manual About This Manual Organization of This Manual Types of Users Software Dependencies Demonstration Database Conventions Typographical Conventions Icon Conventions Syntax Conventions Sample-Code Conventions Terminology Conventions Additional Documentation Printed Documentation On-Line Documentation Related Reading Compliance with Industry Standards Informix Welcomes Your Comments Chapter 1 SQL Statements Categories of SQL Statements ANSI Compliance and Extensions Statements ALLOCATE DESCRIPTOR ALTER INDEX ALTER TABLE BEGIN WORK CLOSE CLOSE DATABASE

4 COMMIT WORK CONNECT CREATE DATABASE CREATE INDEX CREATE PROCEDURE CREATE PROCEDURE FROM CREATE ROLE CREATE SCHEMA AUTHORIZATION CREATE SYNONYM CREATE TABLE CREATE TRIGGER CREATE VIEW DATABASE DEALLOCATE DESCRIPTOR DECLARE DELETE DESCRIBE DISCONNECT DROP DATABASE DROP INDEX DROP PROCEDURE DROP ROLE DROP SYNONYM DROP TABLE DROP TRIGGER DROP VIEW EXECUTE EXECUTE IMMEDIATE EXECUTE PROCEDURE FETCH FLUSH FREE GET DESCRIPTOR GET DIAGNOSTICS GRANT INFO INSERT LOAD LOCK TABLE OPEN OUTPUT PREPARE PUT iv Informix Guide to SQL: Syntax

5 RENAME COLUMN RENAME DATABASE RENAME TABLE REVOKE ROLLBACK WORK SELECT SET SET CONNECTION SET DEBUG FILE TO SET DESCRIPTOR SET EXPLAIN SET ISOLATION SET LOCK MODE SET LOG SET OPTIMIZATION SET ROLE SET SESSION AUTHORIZATION SET TRANSACTION START VIOLATIONS TABLE STOP VIOLATIONS TABLE UNLOAD UNLOCK TABLE UPDATE UPDATE STATISTICS WHENEVER Segments Condition Constraint Name Database Name Data Type DATETIME Field Qualifier Expression Identifier Index Name INTERVAL Field Qualifier Literal DATETIME Literal Interval Literal Number Procedure Name Quoted String Relational Operator Synonym Name Table Name View Name Table of Contents v

6 Chapter 2 SPL Statements CALL CONTINUE DEFINE EXIT FOR FOREACH IF LET ON EXCEPTION RAISE EXCEPTION RETURN TRACE WHILE Multiple-Volume Index vi Informix Guide to SQL: Syntax

7 Introduction Introduction Products Covered in This Manual About This Manual Organization of This Manual Types of Users Software Dependencies Demonstration Database Conventions Typographical Conventions Icon Conventions Comment Icons Product and Platform Icons Compliance Icons Syntax Conventions Elements That Can Appear on the Path How to Read a Syntax Diagram Sample-Code Conventions Terminology Conventions Definitions of Terms Abbreviations of Product Names Additional Documentation Printed Documentation On-Line Documentation Readme Files Release Notes and Machine Notes Error Message Files Related Reading Compliance with Industry Standards Informix Welcomes Your Comments

8 2 Informix Guide to SQL: Syntax

9 This chapter introduces the Informix Guide to SQL: Syntax manual. Read this chapter for an overview of the information provided in this manual and for an understanding of the conventions used throughout this manual. Products Covered in This Manual All the information presented in this manual is valid for the following products. Differences in their use of SQL are indicated where appropriate: INFORMIX-ESQL/C, Version 7.1 INFORMIX-ESQL/COBOL, Version 7.1 INFORMIX-OnLine Workgroup Server, Version 7.12 Relational Object Manager, Version 1.0 DB-Access, Version 7.1 Important: This manual does not cover the product called INFORMIX-SQL or any other Informix application development tool. Each of these tools is covered in its own manual set. This manual is valid only for the products in the preceding list. About This Manual The Informix Guide to SQL: Syntax is intended to be used as a companion volume to the Informix Guide to SQL: Reference and Informix Guide to SQL: Tutorial. This manual and the Informix Guide to SQL: Reference are references that you can use on a daily basis after you finish reading and experimenting with the Informix Guide to SQL: Tutorial. Introduction 3

10 Organization of This Manual This manual contains all the syntax descriptions for Structured Query Language (SQL) and Stored Procedure Language (SPL) statements. The Informix Guide to SQL: Tutorial explains the philosophy and concepts behind relational databases, and the Informix Guide to SQL: Reference provides reference information for aspects of SQL other than the language statements. Organization of This Manual The Informix Guide to SQL: Syntax includes the following chapters: The Introduction explains the purpose and organization of this manual, introduces the demonstration database from which the product examples in the manual are drawn and describes the syntax conventions followed in the manual. Chapter 1, SQL Statements, explains the workings of all the SQL statements that Informix products support. Detailed syntax diagrams walk you through every clause of each SQL statement, and syntax tables explain the input parameters for each clause. Thorough usage instructions, pertinent examples, and references to related material complete the description of each SQL statement. Following the SQL statements in Chapter 1 are descriptions of SQL segments. SQL segments are language elements, such as table names and expressions, that occur in many SQL statements. Instead of describing each segment in each statement where it occurs, this manual provides a comprehensive stand-alone description of each segment. Whenever a segment occurs within a given syntax diagram, the diagram points to the stand-alone description of the segment for further information. Chapter 2, SPL Statements, presents all the detailed syntax diagrams and explanations for SPL statements. You can use stored procedures to perform any function you can perform in SQL as well as to expand what you can accomplish with SQL alone. You write a stored procedure using SPL and SQL statements. For task-oriented information about using stored procedures, see the Informix Guide to SQL: Tutorial. 4 Informix Guide to SQL: Syntax

11 Types of Users The Index is a combined index for the manuals in the SQL series. Each page reference in the index ends with a code that identifies the manual in which the page appears. The same index also appears in the Informix Guide to SQL: Reference and the Informix Guide to SQL: Tutorial. The following items in the SQL manual series are an integral part of the Informix Guide to SQL: Syntax even though they do not appear physically in this manual: A description of the stores7 database appears in Appendix A of the Informix Guide to SQL: Reference. This appendix describes the structure and contents of the demonstration database that is installed with the Informix database server products. All the manuals in the SQL manual series use this database for their examples. Definitions of terms that are used in the SQL manual series appear in the Glossary of the Informix Guide to SQL: Reference. SQL messages that the database server issues to reflect errors in the execution of SQL statements are described in the Informix Error Messages manual. Types of Users This manual is written for people who use Informix products and SQL on a regular basis. The primary audience for this manual consists of SQL developers and database administrators. The secondary audience consists of end users and anyone else who needs to know the syntax of SQL statements. Software Dependencies This manual assumes that you are using INFORMIX-OnLine Workgroup Server, Version 7.12, as your database server. INFORMIX-OnLine Workgroup Server is a multithreaded database server that provides high-availability on-line transaction-processing (OLTP) performance. The functionality provided for client/server communications and for distributed database access is an integral part of OnLine Workgroup Server. Introduction 5

12 Demonstration Database Informix produces a variety of application development tools, database servers, and SQL application programming interfaces (API). DB-Access is a utility that allows you to access, modify, and retrieve information from Informix relational databases. OnLine Workgroup Server supports all application development tools currently available, including INFORMIX-NewEra. SQL APIs currently available include INFORMIX-ESQL/C and INFORMIX-ESQL/COBOL. Demonstration Database The DB-Access utility, which is provided with your Informix database server products, includes a demonstration database called stores7 that contains information about a fictitious wholesale sporting-goods distributor. The sample command files that make up a demonstration application are also included. Most examples in this manual are based on the stores7 demonstration database. The stores7 database is described in detail and its contents are listed in Appendix A of the Informix Guide to SQL: Reference. The script that you use to install the demonstration database is called dbaccessdemo7 and is located in the $INFORMIXDIR/bin directory. The database name that you supply is the name given to the demonstration database. If you do not supply a database name, the name defaults to stores7. Use the following rules for naming your database: Names can have a maximum of 18 characters for INFORMIX-OnLine Workgroup Server databases. The first character of a name must be a letter or an underscore (_). You can use letters, characters, and underscores (_) for the rest of the name. DB-Access makes no distinction between uppercase and lowercase letters. The database name must be unique. When you run dbaccessdemo7, as the creator of the database, you are the owner and Database Administrator (DBA) of that database. 6 Informix Guide to SQL: Syntax

13 Demonstration Database If you install your Informix database server according to the installation instructions, the files that constitute the demonstration database are protected so that you cannot make any changes to the original database. You can run the dbaccessdemo7 script again whenever you want to work with a fresh demonstration database. The script prompts you when the creation of the database is complete and asks if you would like to copy the sample command files to the current directory. Enter N if you have made changes to the sample files and do not want them replaced with the original versions. Enter Y if you want to copy over the sample command files. To create and populate the stores7 demonstration database 1. Set the INFORMIXDIR environment variable so that it contains the name of the directory in which your Informix products are installed. 2. Set INFORMIXSERVER to the name of the default database server. The name of the default database server must exist in the $INFORMIXDIR/etc/sqlhosts file. (For a full description of environment variables, see Chapter 4 of the Informix Guide to SQL: Reference.) For information about sqlhosts, see the INFORMIX-OnLine Workgroup Server Administrator s Guide. 3. Create a new directory for the SQL command files. Create the directory by entering the following command: mkdir dirname 4. Make the new directory the current directory by entering the following command: cd dirname 5. Create the demonstration database and copy over the sample command files by entering the dbaccessdemo7 command. To create the database without logging, enter the following command: dbaccessdemo7 dbname To create the demonstration database with logging, enter the following command: dbaccessdemo7 -log dbname With INFORMIX-OnLine Workgroup Server, by default the data for the database is put into the root dbspace. If you wish, you can specify a dbspace for the demonstration database. Introduction 7

14 Conventions To create a demonstration database in a particular dbspace, enter the following command: dbaccessdemo7 dbname -dbspace dbspacename You can specify all of the options in one command, as shown in the following command: dbaccessdemo7 -log dbname -dbspace dbspacename To use the database and the command files that have been copied to your directory, you must have UNIX read and execute permissions for each directory in the pathname of the directory from which you ran the dbaccessdemo7 script. Check with your system administrator for more information about operating-system file and directory permissions. UNIX permissions are discussed in the INFORMIX-OnLine Workgroup Server Administrator s Guide. 6. To give someone else the permissions to access the command files in your directory, use the UNIX chmod command. 7. To give someone else access to the database that you have created, grant them the appropriate privileges using the GRANT statement. To revoke privileges, use the REVOKE statement. The GRANT and REVOKE statements are described in this manual. Conventions This section describes the conventions that are used in this manual. By becoming familiar with these conventions, you will find it easier to gather information from this and other volumes in the documentation set. The following conventions are covered: Typographical conventions Icon conventions Syntax conventions Sample-code conventions Terminology conventions 8 Informix Guide to SQL: Syntax

15 Typographical Conventions Typographical Conventions This manual uses a standard set of conventions to emphasize words, present examples, describe statement syntax, and so forth. The following typographical conventions are used throughout this manual. Convention italics boldface monospace KEYWORD Meaning Within text, emphasized words are printed in italics. Within syntax diagrams, values that you are to specify are printed in italics. Identifiers (names of classes, objects, constants, events, functions, program variables, forms, labels, and reports), environment variables, database names, table names, column names, menu items, command names, and other similar terms are printed in boldface. Information that the product displays and information that you enter are printed in a monospace typeface. All keywords appear in uppercase letters. This symbol indicates the end of product- or platform-specific information. Tip: When you are instructed to enter characters or to execute a command, immediately press RETURN after the entry. When you are instructed to type the text or to press other keys, no RETURN is required. Icon Conventions Throughout the documentation, you will find text that is identified by several different types of icons. This section describes these icons. Comment Icons Comment icons identify three types of information, as described in the following table. This information is always displayed in italics. Introduction 9

16 Icon Conventions Icon Description Identifies paragraphs that contain vital instructions, cautions, or critical information. Identifies paragraphs that contain significant information about the feature or operation that is being described. Identifies paragraphs that offer additional details or shortcuts for the functionality that is being described. Product and Platform Icons Product and platform icons identify paragraphs that describe productspecific or platform-specific information. The following table describes the product and platform icons that are used in this manual. Icon Description DB ESQL E/C E/CO Identifies information that is valid only for DB-Access. Identifies information that is valid only for SQL statements in INFORMIX-ESQL/C and INFORMIX-ESQL/COBOL. Identifies information that is valid only for INFORMIX-ESQL/C. Identifies information that is valid only for INFORMIX-ESQL/COBOL. 10 Informix Guide to SQL: Syntax

17 Syntax Conventions Icon Description ROM SPL Identifies information that is valid for the Relational Object Manager. Identifies information that is valid if you are using Informix Stored Procedure Language (SPL). These icons can apply to a row in a table, one or more paragraphs, or an entire section. A symbol indicates the end of the product- or platform-specific information. Compliance Icons Compliance icons indicate paragraphs that provide guidelines for complying with a standard. Icon Description ANSI NLS X/O Identifies information that is valid only if your database is ANSI compliant. Identifies information that is valid only if your database or application uses Native Language Support. Indicates that the functionality described in the text conforms to X/Open specifications for dynamic SQL. This functionality is available when you compile your SQL API with the -xopen flag. These icons can apply to a row in a table, one or more paragraphs, or an entire section. A symbol indicates the end of the compliance information. Syntax Conventions This section describes conventions for syntax diagrams. Each diagram displays the sequences of required and optional keywords, terms, and symbols that are valid in a given statement, command line, or other specification, as in the following diagram of the CREATE TABLE statement. Introduction 11

18 Syntax Conventions DB ESQL ROM CREATE + TABLE Table Name p Temp Table Clause p , ( Column ) Definition, p , Table-Level Constraint Definition p Storage Option p The icons stacked in the upper left corner of each syntax diagram indicate which Informix database products and utilities support the SQL statement. Each syntax diagram begins at the upper left corner and ends at the upper right corner with a vertical terminator. Between these points, any path that does not stop or reverse direction describes a possible form of the statement. (For a few diagrams, notes in the text identify path segments that are mutually exclusive.) Syntax elements in a path represent terms, keywords, symbols, and segments that can appear in your statement. Except for separators in loops (e.g, the one above Column Definition ), which the path approaches counterclockwise from the right, the path always approaches elements from the left and continues to the right. Unless otherwise noted, at least one blank character separates syntax elements. Elements That Can Appear on the Path You might encounter one or more of the following elements on a path. 12 Informix Guide to SQL: Syntax

19 Syntax Conventions Element KEYWORD Description A word in UPPERCASE characters is a keyword. You must spell the word exactly as shown; however, you can use either uppercase or lowercase characters. + * - /) Punctuation and other non-alphanumeric characters are literal symbols that you must enter exactly as shown. ' ' variable ADD Clause p ADD Clause E/C Single quotes are literal symbols that you must enter as shown. A word in italics represents a value that you must supply. A table immediately following the diagram explains the value. A term shown in a rectangle represents a subdiagram on the same page (if no page number is supplied) or a specified page, as if the subdiagram were spliced into the diagram at this point. The same subdiagram can be represented by rectangles of different shapes, as in these symbols for the ADD Clause subdiagram. An icon is a warning that this path is valid only for some products, or only under certain conditions. Characters on the icons indicate what products or conditions support the path. These icons might appear in a syntax diagram: DB ESQL E/C E/CO SPL This path is valid only for DB-Access. This path is valid only for SQL statements in INFORMIX-ESQL/C and INFORMIX-ESQL/COBOL. This path is valid only for INFORMIX-ESQL/C. This path is valid only for INFORMIX-ESQL/COBOL. This path is valid only if you are using Informix Stored Procedure Language (SPL). Introduction 13

20 Syntax Conventions Element Description ROM + NLS This path is valid only if you are using ROM. This path is an Informix extension to ANSI SQL-92 entry-level standard SQL. If you initiate Informix extension checking and include this syntax branch, you receive a warning. If you have set the DBANSIWARN environment variable at compile time, or have used the -ansi compile flag, you receive warnings at compile time. If you have DBANSIWARN set at runtime, or if you compiled with the -ansi flag, warning flags are set in the sqlwarn structure. This path is valid only if your database or application uses Natural Language Support. ALL A shaded option is the default. If you do not specify any of the available options, this option is in effect by default. Syntax that is enclosed between a pair of arrows is a subdiagram. The vertical line is a terminator. This symbol only appears at the right, indicating that the syntax diagram is complete. IS NOT NULL A branch below the main path indicates an optional path. (Any term on the main path is required, unless a branch can circumvent it.) 14 Informix Guide to SQL: Syntax

21 Syntax Conventions Element Description NOT FOUND ERROR WARNING, variable statement A set of multiple branches indicates that a choice among more than two different paths is available. A loop indicates a path that you can repeat. Punctuation along the top of the loop indicates the separator symbol for list items, as in this example. If no symbol appears, a blank space is the separator,, A gate ( 3 ) on a path indicates that you can only use 3 size that path the indicated number of times, even if it is part of a larger loop. Here you can specify size no more than three times within this statement segment. Introduction 15

22 Syntax Conventions How to Read a Syntax Diagram Figure 1 shows a syntax diagram that uses most of the path elements that are listed in the previous table. Figure 1 Elements of a Syntax Diagram DB ESQL Main diagram ROM + CREATE DATABASE Database Name p IN dbspace Log Clause Subdiagram Log Clause WITH LOG BUFFERED LOG MODE ANSI The four stacked icons in the upper left corner indicate that this SQL statement is supported by DB-Access, ESQL, and ROM, and that it is an Informix extension to the ANSI SQL-92 entry-level standard SQL. To use this diagram to construct a statement, start at the left with the keywords CREATE DATABASE. Then follow the diagram to the right, proceeding through the options that you want. 16 Informix Guide to SQL: Syntax

23 Sample-Code Conventions To read the example syntax diagram 1. You must type the words CREATE DATABASE. 2. You must supply a database name, which is described in a separate segment called Database Name. 3. You can stop, taking the direct route to the terminator, or you can take one or more of the optional paths. 4. If desired, you can designate a dbspace by typing the word IN and a dbspace name. 5. If desired, you can specify logging. Go to the subdiagram named Log Clause. Follow the subdiagram by typing the keyword WITH, then choosing and typing either LOG, BUFFERED LOG, or LOG MODE ANSI. Then, follow the arrow back to the main diagram. 6. Once you are back at the main diagram, you come to the terminator. Your CREATE DATABASE statement is complete. Sample-Code Conventions Examples of SQL code occur throughout this manual. Except where noted, the code is not specific to any single Informix application development tool. If only SQL statements are listed in the example, they are not delimited by semicolons. To use this SQL code for a specific product, you must apply the syntax rules for that product. For example, if you are using the Querylanguage option of DB-Access, you must delimit multiple statements with semicolons. If you are using an SQL API, you must use EXEC SQL and a semicolon (or other appropriate delimiters) at the start and end of each statement, respectively. For instance, you might see the code in the following example: CONNECT TO stores7... DELETE FROM customer WHERE customer_num = COMMIT WORK DISCONNECT CURRENT Introduction 17

24 Terminology Conventions Dots in the example indicate that more code would be added in a full application, but it is not necessary to show it to describe the concept being discussed. For detailed directions on using SQL statements for a particular application development tool or SQL API, see the manual for your product. Terminology Conventions This manual uses a standard set of conventions for terms and abbreviations. Definitions of Terms For definitions of terms used in this manual and the other manuals of the SQL series, see the Glossary in the Informix Guide to SQL: Reference. Abbreviations of Product Names The following abbreviations for product names appear in this manual. Abbreviation E/C E/CO DB OnLine Workgroup Server ROM SQL Complete Product Name ESQL/C ESQL/COBOL DB-Access INFORMIX-OnLine Workgroup Server Relational Object Manager Structured Query Language 18 Informix Guide to SQL: Syntax

25 Additional Documentation Additional Documentation This section describes the following pieces of the documentation set: Printed documentation On-line documentation Related reading Printed Documentation The following related Informix documents complement the information in this manual set: A companion volume to this manual, the Informix Guide to SQL: Reference, provides reference information on the types of Informix databases you can create, the data types supported in Informix products, system catalog tables associated with the database, and environment variables you can set to use your Informix products properly. This manual also provides a detailed description of the stores7 demonstration database and contains a glossary. An additional companion volume to this manual, the Informix Guide to SQL: Tutorial, provides a tutorial on SQL as it is implemented by Informix products. It describes the fundamental ideas and terminology that are used when planning, using, and implementing a relational database. Managing Relational Objects describes the Relational Object Manager (ROM). This manual explains how to access and use the graphical environment of ROM to manage relational database objects. ROM consists of three components: Database Explorer, SQL Editor, and Table Editor. Introduction 19

26 On-Line Documentation The INFORMIX-ESQL/C Programmer s Manual describes how to write ESQL/C applications. Refer to the INFORMIX-ESQL/C Programmer s Manual for general ESQL/C information. The INFORMIX-ESQL/COBOL Programmer s Manual is a complete guide to the features that make up the Informix implementation of embedded SQL for COBOL. The DB-Access User Manual describes how to invoke the DB-Access utility to access, modify, and retrieve information from Informix database servers. When errors occur, you can look them up by number and learn their cause and solution in the Informix Error Messages manual. If you prefer, you can look up the error messages in the on-line message file described in the section Error Message Files later in this Introduction and in the Introduction to the Informix Error Messages manual. On-Line Documentation Several types of on-line documentation are available: Readme files Release notes and machine notes Error messages Readme Files An ASCII readme.txt file on the server contains information about the server and server agent as well as any last-minute information about installation and documentation changes. This file is located in the /servers directory. On the client side, you can access a readme file of client-only information from the Release Notes icon in the Command Center. An ASCII version of the readme file is located in the /client directory. Release Notes and Machine Notes The following on-line files supplement the information in this manual. 20 Informix Guide to SQL: Syntax

27 Related Reading On-Line File Release notes Machine notes Purpose The SERVERS_7.1 file contains information about any known problems and their workarounds. After server installation, the server release-notes file is located in the directory $INFORMIXDIR/release/ows and is a duplicate of the information in /servers/readme.txt. After client installation, you can access the client release-notes file by double-clicking the Release Notes icon in the INFORMIX-OnLine Workgroup Server program group. This file describes any special actions that are required to configure and use Informix products on your server. The machinenotes file for INFORMIX-OnLine Workgroup Server is ONLINE_7.1 and is located in $INFORMIXDIR/release/ows. Please examine these files because they contain vital information about application and performance issues. Error Message Files If you are accessing OnLine Workgroup Server from a Windows 95 client, you can view files that contain all of the Informix error messages and their corrective actions. To read the error messages, Informix provides the finderr utility. To use the finderr utility, double-click the Informix Find Error icon in the INFORMIX-OnLine Workgroup Server program group. If you are accessing OnLine Workgroup Server from the UNIX server side, you can view ASCII files that contain all of the Informix error messages and their corrective actions. To read the error messages in the ASCII file, Informix provides scripts that let you display error messages on the screen (finderr) or print formatted error messages (rofferr). See the Introduction to Informix Error Messages for a detailed description of these scripts. Related Reading For additional technical information on database management, consult An Introduction to Database Systems by C. J. Date (Addison-Wesley Publishing, 1994). To learn more about the SQL language, consider the following books: Introduction 21

28 Compliance with Industry Standards A Guide to the SQL Standard by C. J. Date with H. Darwen (Addison- Wesley Publishing, 1993) Understanding the New SQL: A Complete Guide by J. Melton and A. Simon (Morgan Kaufmann Publishers, 1993) Using SQL by J. Groff and P. Weinberg (Osborne McGraw-Hill, 1990) This manual assumes that you are familiar with your computer operating system. If you have limited UNIX system experience, consult your operating system manual or a good introductory text before you read this manual. The following texts provide a good introduction to UNIX systems: Introducing the UNIX System by H. McGilton and R. Morgan (McGraw-Hill Book Company, 1983) Learning the UNIX Operating System by G. Todino, J. Strang, and J. Peek (O Reilly & Associates, 1993) A Practical Guide to the UNIX System by M. Sobell (Benjamin/Cummings Publishing, 1989) UNIX for People by P. Birns, P. Brown, and J. Muster (Prentice-Hall, 1985) UNIX System V: A Practical Guide by M. Sobell (Benjamin/Cummings Publishing, 1995) Compliance with Industry Standards The American National Standards Institute (ANSI) has established a set of industry standards for SQL. Informix SQL-based products are fully compliant with SQL-92 Entry Level (published as ANSI X ), which is identical to ISO 9075:1992 on INFORMIX-OnLine Workgroup Server. In addition, many features of OnLine Workgroup Server comply with the SQL-92 Intermediate and Full Level and X/Open CAE (common applications environment) standards. 22 Informix Guide to SQL: Syntax

29 Informix Welcomes Your Comments Informix Welcomes Your Comments Please let us know what you like or dislike about our manuals. To help us with future versions of our manuals, please tell us about any corrections or clarifications that you would find useful. Include the following information: The name and version of the manual that you are using Any comments that you have about the manual Your name, address, and phone number Write to us at the following address: Informix Software, Inc. SCT Technical Publications Department 4100 Bohannon Drive Menlo Park, CA If you prefer to send electronic mail, our address is: Or send a facsimile to the Informix Technical Publications Department at: We appreciate your feedback. Introduction 23

30

31 SQL Statements Chapter 1 Categories of SQL Statements ANSI Compliance and Extensions Statements ALLOCATE DESCRIPTOR ALTER INDEX ALTER TABLE BEGIN WORK CLOSE CLOSE DATABASE COMMIT WORK CONNECT CREATE DATABASE CREATE INDEX CREATE PROCEDURE CREATE PROCEDURE FROM CREATE ROLE CREATE SCHEMA AUTHORIZATION CREATE SYNONYM CREATE TABLE CREATE TRIGGER CREATE VIEW DATABASE DEALLOCATE DESCRIPTOR DECLARE DELETE DESCRIBE DISCONNECT DROP DATABASE DROP INDEX

32 Informix Guide to SQL: Syntax DROP PROCEDURE DROP ROLE DROP SYNONYM DROP TABLE DROP TRIGGER DROP VIEW EXECUTE EXECUTE IMMEDIATE EXECUTE PROCEDURE FETCH Using the INTO Clause of EXECUTE PROCEDURE FLUSH FREE GET DESCRIPTOR GET DIAGNOSTICS GRANT INFO INSERT LOAD LOCK TABLE OPEN OUTPUT PREPARE PUT RENAME COLUMN RENAME DATABASE RENAME TABLE REVOKE ROLLBACK WORK SELECT SET SET CONNECTION SET DEBUG FILE TO SET DESCRIPTOR SET EXPLAIN SET ISOLATION SET LOCK MODE SET LOG SET OPTIMIZATION SET ROLE SET SESSION AUTHORIZATION

33 SET TRANSACTION START VIOLATIONS TABLE STOP VIOLATIONS TABLE UNLOAD UNLOCK TABLE UPDATE UPDATE STATISTICS WHENEVER Segments Condition Constraint Name Database Name Data Type DATETIME Field Qualifier Expression Identifier Index Name INTERVAL Field Qualifier Literal DATETIME Literal Interval Literal Number Procedure Name Quoted String Relational Operator Synonym Name Table Name View Name SQL Statements

34 Informix Guide to SQL: Syntax

35 PREPARE PREPARE Use the PREPARE statement to parse, validate, and generate an execution plan for SQL statements in an SQL API program at runtime. Syntax ESQL + PREPARE statement id FROM Quoted String p statement id variable statement variable name Element Purpose Restrictions Syntax statement id The statement identification identifies an SQL statement After you release the databaseserver resources (using a FREE statement), you cannot use the statement identifier with a DECLARE cursor or with the EXECUTE statement until you prepare the statement again. Identifier, p statement id variable statement variable name Host variable that identifies an SQL statement Host variable whose value is a character string consisting of one or more SQL statements This variable must be a character data type. This variable must be a character data type. For a list of restrictions, see Restrictions for Multistatement Prepares on page For a list of allowed statements, see Permitted Statements on page Identifier, p Variable name must conform to language-specific rules for variable names. SQL Statements 1-329

36 PREPARE Usage The PREPARE statement permits your program to assemble the text of an SQL statement at runtime and make it executable. This dynamic form of SQL is accomplished in three steps: 1. A PREPARE statement accepts statement text as input, either as a quoted string or stored within a character variable. Statement text can contain question-mark (?) placeholders to represent values that are to be defined when the statement is executed. 2. An EXECUTE or OPEN statement can supply the required input values and execute the prepared statement once or many times. 3. Resources allocated to the prepared statement can be released later using the FREE statement. The number of prepared objects in a single program is limited by the available memory. This includes both statement identifiers that are named in PREPARE statements (statement id or statement id variable) and cursor declarations that incorporate SELECT, EXECUTE PROCEDURE, or INSERT statements. To avoid exceeding the limit, use a FREE statement to release some statements or cursors. Statement Identifier A PREPARE statement sends the statement text to the database server where it is analyzed. If it contains no syntax errors, the text converts to an internal form. This translated statement is saved for later execution in a data structure that the PREPARE statement allocates. The name of the structure is the value that is assigned to the statement identifier in the PREPARE statement. Subsequent SQL statements refer to the structure by using the same statement identifier that was used in the PREPARE statement. A subsequent FREE statement releases the resources that were allocated to the statement. After you release the database-server resources, you cannot use the statement identifier with a DECLARE cursor or with the EXECUTE statement until you prepare the statement again. A program can consist of one or more source-code files. By default, the scope of a statement identifier is global to the program. Therefore, a statement identifier that is prepared in one file can be referenced from another file Informix Guide to SQL: Syntax

37 PREPARE In a multiple-file program, if you want to limit the scope of a statement identifier to the file in which it is prepared, preprocess all the files with the -local command-line option. See the manual for your SQL API for more information, restrictions, and performance issues when you are preprocessing with the -local option. Releasing a Statement Identifier A statement identifier can represent only one SQL statement or sequence of statements at a time. You can execute a new PREPARE statement with an existing statement identifier if you wish to bind a given statement identifier to a different SQL statement text. The PREPARE statement supports dynamic statement-identifier names, which allow you to prepare a statement identifier as an identifier or as a host character-string variable. In the following ESQL/C and ESQL/COBOL examples, the first example in each pair shows a statement identifier that was prepared as an SQL API variable; the second example in each pair shows a statement identifier that was prepared as a character-string constant: INFORMIX-ESQL/C strcpy (stmtid, "query2"); EXEC SQL prepare :stmtid from 'select * from customer'; EXEC SQL prepare query2 from 'select * from customer'; INFORMIX-ESQL/COBOL MOVE 'QUERY_2' TO STMTID. EXEC SQL PREPARE :STMTID FROM 'SELECT * FROM CUSTOMER' END-EXEC. EXEC SQL PREPARE QUERY_2 FROM 'SELECT * FROM CUSTOMER' END-EXEC. A statement ID variable must be the CHARACTER data type. In C, it must be defined as char. In COBOL, ID variables must be declared as a standard CHARACTER type. SQL Statements 1-331

38 PREPARE Statement Text The PREPARE statement can take statement text either as a quoted string or as text that is stored in a program variable. The following restrictions apply to the statement text: The text can contain only SQL statements. It cannot contain statements or comments from the host programming language. Comments that are preceded by two hyphens (--) or enclosed in curly braces ({ }) are standard in SQL and are allowed in the statement text. The comment ends at the end of the line or at the end of the statement. The text can contain either a single SQL statement or a sequence of statements that are separated by semicolons. Names of host-language variables are not recognized as such in prepared text. The only identifiers that you can use are names that are defined in the database, such as names of tables and columns. Therefore, you cannot prepare a SELECT statement that contains an INTO clause or an EXECUTE PROCEDURE that contains an INTO clause because the INTO clause requires a host-language variable. Use a question mark (?) as a placeholder to indicate where data is supplied when the statement executes. The text cannot include an embedded SQL statement prefix or terminator, such as a dollar sign ($) or the words EXEC SQL. The following example shows a PREPARE statement in INFORMIX-ESQL/C: EXEC SQL prepare new_cust from 'insert into customer(fname,lname) values(?,?)' Informix Guide to SQL: Syntax

39 PREPARE Executing Stored Procedures Within a PREPARE Statement You can prepare an EXECUTE PROCEDURE statement as long as it does not contain an INTO clause. The way to execute a prepared stored procedure depends on whether the stored procedure returns values: If the stored procedure does not return values (the procedure does not contain the RETURN statement), use the EXECUTE statement to execute the EXECUTE PROCEDURE statement. If the stored procedure returns only one row, you can use the INTO clause of the EXECUTE statement to specify host variables to hold the return values. Using EXECUTE... INTO to execute a stored procedure that returns more than one row generates a runtime error. If the stored procedure returns more than one row, you must associate the prepared EXECUTE PROCEDURE statement with a cursor using the DECLARE statement. You execute the statement with the OPEN statement and retrieve return values into host variables using the INTO clause of the FETCH statement. If you do not know the number and data types of the values that a stored procedure returns, you must use a dynamic-management structure to hold the returned values. In an ESQL/C or ESQL/COBOL program, you can use SQL statements such as ALLOCATE DESCRIPTOR and GET DESCRIPTOR to manage a system-descriptor area. In an ESQL/C program, you can use an sqlda structure instead of a system-descriptor area. However, a systemdescriptor area conforms to the X/Open standards. See Chapter 12 of the Informix Guide to SQL: Tutorial for information about creating and executing stored procedures. See the INFORMIX-ESQL/COBOL Programmer s Manual and the INFORMIX-ESQL/C Programmer s Manual for detailed information about using dynamic-management structures to dynamically execute a stored procedure. SQL Statements 1-333

40 PREPARE Permitted Statements You can prepare any single SQL statement except the ones in the following list. ALLOCATE DESCRIPTOR CLOSE DEALLOCATE DESCRIPTOR DECLARE DESCRIBE EXECUTE IMMEDIATE EXECUTE FETCH FLUSH FREE GET DESCRIPTOR GET DESCRIPTOR GET DIAGNOSTICS INFO LOAD OPEN OUTPUT PREPARE PUT REPAIR TABLE SET DESCRIPTOR UNLOAD WHENEVER You can prepare a SELECT statement. If the SELECT statement includes the INTO TEMP clause, you can execute the prepared statement with an EXECUTE statement. If it does not include the INTO TEMP clause, the statement returns rows of data. Use DECLARE, OPEN, and FETCH cursor statements to retrieve the rows. A prepared SELECT statement can include a FOR UPDATE clause. This clause is normally used with the DECLARE statement to create an update cursor. The following example shows a SELECT statement with a FOR UPDATE clause in INFORMIX-ESQL/C: sprintf(up_query, "%s %s %s", "select * from customer ", "where customer_num between? and? ", "for update"); EXEC SQL prepare up_sel from :up_query; EXEC SQL declare up_curs cursor for up_sel; EXEC SQL open up_curs using :low_cust,:high_cust; Informix Guide to SQL: Syntax