HP NonStop SQL Programming Manual for TAL

Transcription

1 HP NonStop SQL Programming Manual for TAL Abstract This manual describes the programmatic interface to HP NonStop SQL for the Transaction Application Language (TAL). The NonStop SQL relational database management system (RDBMS) uses the structured query language (SQL) to describe and manipulate data in NonStop SQL databases. This manual is intended for application programmers who are coding embedded SQL statements in a TAL program. Product Version NonStop SQL C30 Supported Release Version Updates (RVUs) This publication supports D40.00 and all subsequent D-series RVUs and G06.00 and all subsequent G-series RVUs until otherwise indicated by its replacement publication. Part Number Published March 2004

2 Document History Part Number Product Version Published N.A. NonStop SQL C30 September 1990 N.A. NonStop SQL C30 December NonStop SQL C30 March 2004

3 HP NonStop SQL Programming Manual for TAL Index Figures Tables What s New in This Manual ix Manual Information ix New and Changed Information ix About This Manual xi Audience xi Organization xii Related Manuals xii Notation Conventions xv 1. Introduction Why Use Embedded SQL Statements? 1-1 Developing a Program 1-2 Embedding SQL Statements 1-2 Declaring Host Variables 1-3 Calling SQL System Procedures 1-3 Using Static SQL Statements 1-4 Using Dynamic SQL Operations 1-5 Compiling and Executing a Program Host Variables and Parameters Host Variables 2-1 Declaring Host Variables 2-2 Using Corresponding SQL and TAL Data Types 2-2 Overriding Default Data Types 2-5 Using Host Variables 2-6 Using Indicator Variables for Null Values 2-17 Creating Host Variables With the INVOKE Directive 2-20 Parameters 2-23 Using a Parameter List 2-24 Using Parameters in Loops 2-25 Using Indicator Parameters 2-25 Using Default Parameter Data Types 2-26 Hewlett-Packard Company i

4 Contents 3. NonStop SQL Statements and Directives 3. NonStop SQL Statements and Directives Embedding SQL Statements and Directives 3-1 Coding Statements and Directives 3-2 Placing Statements and Directives in a Program 3-2 Locating Information About SQL Statements and Directives 3-4 BEGIN DECLARE SECTION and END DECLARE SECTION 3-6 CLOSE 3-7 CONTROL Directives 3-8 DECLARE CURSOR 3-11 DELETE 3-13 DESCRIBE and DESCRIBE INPUT 3-16 DROP 3-17 EXECUTE and EXECUTE IMMEDIATE 3-18 FETCH 3-18 INCLUDE SQLCA, INCLUDE SQLDA, and INCLUDE SQLSA 3-19 INSERT 3-19 INVOKE 3-22 OPEN 3-29 PREPARE 3-30 RELEASE 3-31 SELECT 3-31 SQL 3-35 SQLMEM 3-37 SYMBOLPAGES 3-42 UPDATE 3-42 WHENEVER System Procedures Procedure Descriptions 4-2 SQLCADISPLAY 4-2 SQLCAFSCODE 4-7 SQLCAGETINFOLIST 4-8 SQLCATOBUFFER 4-13 SQLGETCATALOGVERSION 4-19 SQLGETOBJECTVERSION 4-19 SQLGETSYSTEMVERSION 4-21 SQLSADISPLAY 4-22 ii

5 Contents 5. Program Compilation and Execution 5. Program Compilation and Execution Compiling a TAL Program 5-2 Running the TAL Compiler 5-3 Using the Binder Program 5-4 Including the TALLIB Run-Time Library 5-4 Running the Accelerator 5-5 Running the SQL Compiler 5-5 Using the EXPLAIN Utility 5-17 Determining Program File Validity 5-22 Changes to a Program File 5-22 Changes to Database Objects 5-23 Other Changes 5-23 Understanding Automatic SQL Recompilation 5-24 Predicting Automatic SQL Recompilation 5-24 Understanding the Run-Time Timestamp Check 5-26 Understanding Run-Time Recompilation Errors 5-28 Maximizing Local Autonomy 5-28 Using a Local Partition 5-28 Using TACL DEFINEs 5-29 Using Current Statistics 5-29 Skipping Unavailable Partitions 5-30 Executing an SQL Program File 5-30 Using the RUN Command 5-30 Using TACL DEFINEs 5-31 Estimating Program Size Error and Status Processing Getting Error and Warning Information 6-1 Using the SQLCODE Variable 6-1 Using the WHENEVER Directive 6-4 Getting Information From the SQLCA 6-9 Getting Performance and Statistics Information 6-10 Getting Information About Dynamic SQL Operations 6-13 Declaring the SQLDA and Names Buffer 6-14 Initializing the EYE^CATCHER Field 6-18 Using Literal Declarations for the SQLDA 6-18 Example of Using the SQLDA 6-21 iii

6 Contents 7. Dynamic NonStop SQL Operations 7. Dynamic NonStop SQL Operations Determining Uses for Dynamic SQL Operations 7-2 Developing a Dynamic SQL Application 7-2 Writing a Dynamic SQL Pathway Server 7-3 Specifying Input Parameters and Output Variables 7-4 Using the SQLDA and Names Buffer 7-5 Using Dynamic SQL Programming Techniques 7-7 Overview of a Dynamic SQL Program 7-7 Dynamically Allocating Memory 7-14 Using the Names Buffer 7-23 Allocating and Filling in Output Variables 7-27 Using Dynamic Cursors 7-31 Using Statement and Cursor Host Variables 7-33 Handling Null Values 7-36 A. Sample NonStop SQL Database B. Examples of Static NonStop SQL Programs Insertion Program B-1 Date-Time Program B-10 C. Examples of Dynamic NonStop SQL Programs Dynamic SQL Program C-1 Detailed Dynamic SQL Program C-9 D. NonStop SQL Version Issues Version 1 and Version 2 Definitions D-1 Summary of Incompatible Changes D-3 Migrating a C10 Program to Run on a C30 System D-4 Migrating a C10 Program to Access Version 2 Objects D-7 Dynamic SQL Operations D-7 Static SQL Operations D-8 Catalog Tables D-8 Summary D-8 Installing Migrated Programs D-8 SQL Component Compatibility D-9 Developing C10 Programs with C30 Software D-10 Binding C10 and C30 Object Files D-10 Mixed-Version Programmatic Features D-11 Release Specification Options D-11 iv

7 Contents D. NonStop SQL Version Issues (continued) D. NonStop SQL Version Issues (continued) System Procedures D-11 Techniques for Mixed-Version Programming D-12 Handling Mixed-Version-Objects D-12 Running on Multiple NonStop SQL Releases D-13 Using the Single-Code Thread Design D-14 E. Enforcing Data Integrity Index Figures Using Constraints E-1 Managing Referential Integrity E-2 Figure i. Related Manuals xiv Figure 1-1. Static SQL Statements in a TAL Program 1-5 Figure 1-2. Dynamic SQL Statements in a TAL Program 1-6 Figure 1-3. Compiling and Executing a Program 1-8 Figure 4-1. SQLSADISPLAY Display 4-24 Figure 5-1. Compiling and Executing a Program 5-2 Figure 5-2. NonStop SQL Program File Format 5-12 Figure 5-3. Sample SQL Compiler Listing 5-16 Figure 5-4. OBEY Command File Format of the EXPLAIN DEFINES Report 5-19 Figure 5-5. INFO DEFINE Format of the EXPLAIN DEFINES Report 5-20 Figure 5-6. EXPLAIN Utility Report 5-21 Figure 5-7. Run-Time Checks and Automatic SQL Recompilation 5-27 Figure 6-1. Checking the SQLCODE Variable 6-3 Figure 6-2. Enabling and Disabling the WHENEVER Directive 6-6 Figure 6-3. Using WHENEVER Directives 6-8 Figure 6-4. Calling an SQL System Procedure 6-10 Figure 6-5. SQLSA Structure Description 6-11 Figure 6-6. Release C30 SQLDA Template and Names Buffer 6-15 Figure 6-7. Release C10 SQLDA Template and Names Buffer 6-16 Figure 6-8. SQLDA Structure Template 6-22 Figure 7-1. Using a PREPARE Statement to Compile a Statement 7-16 Figure 7-2. Allocating the SQLDA Structure 7-19 Figure 7-3. Allocating Memory for Values 7-22 Figure 7-4. Getting Parameter Values 7-25 Figure 7-5. Displaying Output 7-29 Figure 7-6. Statement and Cursor Host Variables 7-34 v

8 Contents Figures (continued) Figures (continued) Tables Figure A-1. Sample NonStop SQL Database Relations A-2 Figure A-2. Sample Database Source File A-3 Figure B-1. Insertion Program Output B-2 Figure B-2. Date-Time Program Run B-12 Figure C-1. Output for the Dynamic SQL Program C-2 Figure C-2. Output for the Detailed Dynamic SQL Program C-11 Figure D-1. Developing a Program For Mixed-Version Nodes D-15 Table 1-1. NonStop SQL Statements 1-2 Table 1-2. NonStop SQL Directives 1-3 Table 2-1. Corresponding NonStop SQL and TAL Data Types 2-3 Table 2-2. Default and Override Data Type Mapping 2-6 Table 2-3. Date-Time and INTERVAL Data Types 2-16 Table 2-4. INVOKE Directive Override Data Type Mapping 2-20 Table 3-1. Summary of NonStop SQL Statements and Directives 3-4 Table 3-2. INVOKE Directive Override Data Type Mapping 3-23 Table 3-3. NonStop SQL Data Structures 3-38 Table 4-1. System Procedures for NonStop SQL Operations 4-1 Table 4-2. SQLCAGETINFOLIST Procedure Item Codes 4-11 Table 4-3. SQLCAGETINFOLIST Procedure Error Codes 4-12 Table 4-4. NonStop SQL Release C30 (Version 2) Features 4-20 Table 4-5. SQLSADISPLAY Procedure Display Elements 4-23 Table 5-1. Calculating Virtual Memory Requirements for Each SQL Statement or Directive 5-33 Table 6-1. TAL Compiler Pseudocode for Checking SQLCODE 6-4 Table 6-2. System Procedures for the SQLCA Structure 6-9 Table 6-3. SQLSA Fields 6-11 Table 6-4. SQLDA Fields 6-17 Table 6-5. Literal Declarations for Character, Numeric, and Decimal Values 6-19 Table 6-6. Literal Declarations for Date-Time and INTERVAL Values 6-19 Table 6-7. Literal Declarations for Ranges of Date-Time Fields 6-20 Table 7-1. Literal Declarations for Data Types 7-21 Table D-1. Version 2 Items and Descriptions D-2 Table D-2. Version 1 Items and Descriptions D-2 Table D-3. Summary of New Columns in Version 2 Catalogs D-3 Table D-4. Incompatible NonStop SQL Release C30 Features D-4 vi

9 Contents Tables (continued) Tables (continued) Table D-5. Accessing Version 2 Objects from a C10 Program D-8 Table D-6. Release C10 Versioning IPM Summary D-9 vii

10 Contents viii

11 What s New in This Manual Manual Information Abstract HP NonStop SQL Programming Manual for TAL This manual describes the programmatic interface to HP NonStop SQL for the Transaction Application Language (TAL). The NonStop SQL relational database management system (RDBMS) uses the structured query language (SQL) to describe and manipulate data in NonStop SQL databases. This manual is intended for application programmers who are coding embedded SQL statements in a TAL program. Product Version NonStop SQL C30 Supported Release Version Updates (RVUs) This publication supports D40.00 and all subsequent D-series RVUs and G06.00 and all subsequent G-series RVUs until otherwise indicated by its replacement publication. Part Number Published March 2004 Document History Part Number Product Version Published N.A. NonStop SQL C30 September 1990 N.A. NonStop SQL C30 December NonStop SQL C30 March 2004 New and Changed Information This publication has been updated to reflect new product names: Since product names are changing over time, this publication might contain both HP and Compaq product names. Product names in graphic representations are consistent with the current product interface. The technical content of this publication has not been updated and reflects the state of the product at the G06.22 release version update (RVU). ix

12 What s New in This Manual New and Changed Information x

13 About This Manual This manual describes the programmatic interface to NonStop SQL for the Transaction Application Language (TAL). The NonStop SQL relational database management system (RDBMS) uses the structured query language (SQL) to define and manipulate data in NonStop SQL databases. NonStop SQL provides both a conversational and a programmatic interface. Using the programmatic interface, a C, COBOL85, Pascal, or TAL programmer can use embedded SQL statements to access a NonStop SQL database. Audience This manual is intended for TAL programmers who are coding embedded SQL statements in a TAL program. A reader should be familiar with: TAL NonStop SQL terms and concepts (as described in the Introduction to NonStop SQL) The HP NonStop Kernel operating system Organization Section 1 Section 2 Section 3 Section 4 Section 5 Section 6 Section 7 Appendix A Appendix B Appendix C Appendix D Appendix E Provides an overview of the TAL programmatic interface to NonStop SQL. Describes how to declare and use host variables and parameters in a TAL program. Describes the statements and directives that have unique TAL considerations, data structures, or examples. Describes the SQL system library procedures and shows how to call them from a TAL program. Describes how to compile and execute a TAL program that contains embedded SQL statements. Describes how to process error and status messages and statistics information using the SQLCODE variable and the SQLCA, SQLDA, and SQLSA data structures. Describes how to use dynamic SQL operations. Describes the sample NonStop SQL database that is used by the programming examples. Includes two programming examples that use static SQL operations. Includes two programming examples that use dynamic SQL operations. Describes version issues for NonStop SQL release C10 and release C30 software. Describes how to use constraints and to check for referential integrity. xi

14 About This Manual Related Manuals Related Manuals You will probably want to use other books from the SQL/MP library set, shown in Figure i, in conjunction with this reference manual. The complete library includes: The SQL/MP Reference Manual describes the SQL/MP language elements, expressions, predicates, functions, and SQL statements that can be run in SQLCI. The manual also describes SQLCI commands and utilities. Optional NonStop SQL/MP Library Manuals Introduction to SQL/MP provides an overview of the SQL/MP relational database management system. The SQL/MP Messages Manual describes NonStop SQL messages. The SQL/MP Installation and Management Guide explains how to plan, install, create, and manage a SQL database. The SQL/MP Programming Manual for C and SQL/MP Programming Manual for COBOL85 describe the SQL/MP programmatic interfaces for C and COBOL85, respectively. The SQL/MP Programming Manual for Pascal and SQL/MP Programming Manual for TAL are the equivalent manuals for Pascal and TAL. Program Development Manuals The TAL Reference Manual describes TAL. The Inspect Manual describes the Inspect program, an interactive source-level or machine-level debugger that enables you to interrupt and resume program execution and to display and modify variables. The Guardian Programmer s Guide describes the programmatic interface between user programs and the operating system. The Binder Manual describes the Binder program, an interactive linker that enables you to examine, modify, and combine object files and to generate load maps and cross-reference listings. If plan to run your object file on a TNS/R system and you use the Accelerator to optimize the object code, see the Accelerator Manual. xii

15 About This Manual Related Manuals Figure i. Related Manuals Related Manuals Introduction to SQL/MP Prerequisite Manual SQL Programming Manual for TAL Companion Manual SQL/MP Reference Manual Program Development Manuals Optional NonStop SQL Manuals TAL Reference Manual Inspect Manual SQL /MP Messages Manual SQL /MP Installation and Management Guide Guardian' Programmer's Guide Binder Manual SQL/MP Version Management Guide SQL/MP Reference Summary Other NonStop SQL Programming Manuals SQL/MP Programming Manual for C SQL/MP Programming Manual for COBOL85 SQL/MP Programming Manual for Pascal VSTAB01.vsd xiii

16 About This Manual Notation Conventions Notation Conventions The list summarizes the conventions used for syntax and programming examples in this manual. Notation UPPERCASE LETTERS lowercase italic letters Brackets [ ] Braces { } Vertical line Ellipsis... Spaces i and o Punctuation Meaning Uppercase letters represent keywords and reserved words; enter these items exactly as shown. Uppercase letters in text also represent variable names that are used in programming examples. Lowercase letters in italics represent information you supply. Brackets enclose optional syntax items. A group of vertically aligned items enclosed in brackets represents a list of selections from which you can choose one or none. Braces enclose required syntax items. A group of vertically aligned items enclosed in braces represents a list of selections from which you must choose one. A vertical line separates alternative syntax items in a horizontal list. Such a list, enclosed in either brackets or braces, is an alternative to a vertical list for presenting selections. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed syntax items any number of times. An ellipsis in a programming example indicates that one or more lines of source code have been omitted. If a space separates two items, that space is required. If one of the items is a punctuation symbol, such as a parenthesis or a comma, spaces are optional. In the syntax for SQL system procedure calls, i and o are used as follows: i Input parameters (parameters that pass data to the called procedure) o Output parameters (parameters that return data to the calling program) i:o Input and output parameters (parameters that both pass and return data) Parentheses, commas, semicolons, and other symbols not described above must be entered precisely as shown. xiv

17 About This Manual Hypertext Links Hypertext Links Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described. For example: This requirement is described under Backup DAM Volumes and Physical Disk Drives on page 3-2. General Syntax Notation This list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.c italic computer type. Italic computer type letters within text indicate C and Open System Services (OSS) variable items that you supply. Items not enclosed in brackets are required. For example: pathname [ ] Brackets. Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: FC [ num ] [ -num ] [ text ] K [ X D ] address { } Braces. A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list can be arranged either vertically, with aligned xv

18 About This Manual General Syntax Notation braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LISTOPENS PROCESS { $appl-mgr-name } { $process-name } ALLOWSU { ON OFF } Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: INSPECT { OFF ON SAVEABEND } Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address [, new-value ] [ - ] { } An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char " Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.#su-name Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown. For example: "[" repetition-constant-list "]" Item Spacing. Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: CALL STEPMOM ( process-id ) ; If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items: $process-name.#su-name Line Spacing. If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: ALTER [ / OUT file-spec / ] LINE [, attribute-spec ] xvi

19 About This Manual Notation for Messages!i and!o. In procedure calls, the!i notation follows an input parameter (one that passes data to the called procedure); the!o notation follows an output parameter (one that returns data to the calling program). For example: CALL CHECKRESIZESEGMENT ( segment-id!i, error ) ;!o!i,o. In procedure calls, the!i,o notation follows an input/output parameter (one that both passes data to the called procedure and returns data to the calling program). For example: error := COMPRESSEDIT ( filenum ) ;!i,o!i:i. In procedure calls, the!i:i notation follows an input string parameter that has a corresponding parameter specifying the length of the string in bytes. For example: error := FILENAME_COMPARE_ ( filename1:length!i:i, filename2:length ) ;!i:i!o:i. In procedure calls, the!o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes. For example: error := FILE_GETINFO_ ( filenum!i, [ filename:maxlen ] ) ;!o:i Notation for Messages This list summarizes the notation conventions for the presentation of displayed messages in this manual. Bold Text. Bold text in an example indicates user input typed at the terminal. For example: ENTER RUN CODE?123 CODE RECEIVED: The user must press the Return key after typing the input. Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or returned exactly as shown. For example: Backup Up. lowercase italic letters. Lowercase italic letters indicate variable items whose values are displayed or returned. For example: p-register process-name xvii

20 About This Manual Notation for Management Programming Interfaces [ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For example: Event number = number [ Subject = first-subject-value ] A group of items enclosed in brackets is a list of all possible items that can be displayed, of which one or none might actually be displayed. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: proc-name trapped [ in SQL in SQL file system ] { } Braces. A group of items enclosed in braces is a list of all possible items that can be displayed, of which one is actually displayed. The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: obj-type obj-name state changed to state, caused by { Object Operator Service } process-name State changed from old-objstate to objstate { Operator Request. } { Unknown. } Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: Transfer status: { OK Failed } % Percent Sign. A percent sign precedes a number that is not in decimal notation. The % notation precedes an octal number. The %B notation precedes a binary number. The %H notation precedes a hexadecimal number. For example: % %B %H2F P=%p-register E=%e-register Notation for Management Programming Interfaces This list summarizes the notation conventions used in the boxed descriptions of programmatic commands, event messages, and error lists in this manual. UPPERCASE LETTERS. Uppercase letters indicate names from definition files. Type these names exactly as shown. For example: ZCOM-TKN-SUBJ-SERV xviii

21 About This Manual Change Bar Notation lowercase letters. Words in lowercase letters are words that are part of the notation, including Data Definition Language (DDL) keywords. For example: token-type!r.!o. The!r notation following a token or field name indicates that the token or field is required. For example: ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING.!r The!o notation following a token or field name indicates that the token or field is optional. For example: ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32.!o Change Bar Notation Change bars are used to indicate substantive differences between this edition of the manual and the preceding edition. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, examples, and so on. Change bars highlight new or revised information. For example: The message types specified in the REPORT clause are different in the COBOL85 environment and the Common Run-Time Environment (CRE). The CRE has many new message types and some new message type codes for old message types. In the CRE, the message type SYSTEM includes all messages except LOGICAL-CLOSE and LOGICAL-OPEN. xix

22 About This Manual Change Bar Notation xx

23 1 Introduction The NonStop SQL relational database management system (RDBMS) uses the structured query language (SQL) to define and manipulate data in a NonStop SQL database. Because NonStop SQL is integrated with other HP NonStop software products, you can execute SQL statements interactively or programmatically. Using the SQL conversational interface (SQLCI), you can enter SQL statements and directives interactively from a terminal or an OBEY command file. NonStop SQL compiles and executes the statement immediately and then issues a response at your terminal. Using SQLCI, you can also test programmatic SQL statements before you embed and compile them in a program. Using the programmatic interface, you can embed SQL statements and directives in a C, COBOL85, Pascal, or TAL program. You compile the host language statements using the host language compiler and the embedded SQL statements using the SQL compiler. The SQL statements execute when the object file runs. NonStop SQL also provides system library procedures you can call from a program to perform various SQL functions (for example, to get error and statistics information after executing an SQL statement). This manual describes the TAL programmatic interface to NonStop SQL. It shows you how to embed SQL statements and directives in a TAL program and how to call the SQL system library procedures from a TAL program. Why Use Embedded SQL Statements? Using embedded SQL statements in a TAL program to access a NonStop SQL database has these advantages: High-level language for accessing a database. Using SQL statements, you code a request to access a database, and NonStop SQL determines the most efficient method to perform the request. Insulation against database changes. If a database administrator modifies a database (for example, adds columns to a table), the logic of your program is not affected. Use of TAL for processing data. You can use SQL statements to retrieve data from a database or insert data into a database, and you can use TAL statements to process and manipulate the data. System support for data consistency. When you use audited tables and views, the system maintains data consistency with the locking facility and the HP NonStop Transaction Manangement Facility (TMF). 1-1

24 Introduction Developing a Program Developing a Program A TAL program that contains embedded SQL statements can use both static and dynamic SQL operations. A static SQL operation processes SQL statements that you embed and compile in the TAL source code. A dynamic SQL operation enables a program to construct, compile, and execute an SQL statement at run time. Embedding SQL Statements You embed SQL statements by preceding each SQL statement with the keywords EXEC SQL and terminating the statement with either a semicolon (;) or an END, ELSE, or UNTIL keyword if it is appropriate for the statement. This example shows a TAL source file that contains embedded SQL statements.! TAL source file... EXEC SQL BEGIN DECLARE SECTION;... ;! SQL host variable declarations EXEC SQL END DECLARE SECTION;...! TAL procedure... EXEC SQL... ;! SQL statement... Table 1-1 shows the NonStop SQL statements you can embed in a TAL program. Table 1-1. NonStop SQL Statements Type Data Control Language (DCL) Data Definition Language (DDL) Data Manipulation Language (DML) Dynamic SQL Transaction Control Statement FREE RESOURCES, LOCK TABLE, UNLOCK TABLE ALTER, COMMENT, CREATE, DROP, HELP TEXT, UPDATE STATISTICS CLOSE, DECLARE CURSOR, DELETE, FETCH, INSERT, OPEN, SELECT, UPDATE DECLARE CURSOR, DESCRIBE, DESCRIBE INPUT, EXECUTE, EXECUTE IMMEDIATE, PREPARE, RELEASE BEGIN WORK, COMMIT WORK, ROLLBACK WORK 1-2

25 Introduction Declaring Host Variables Table 1-2 shows the NonStop SQL directives you can embed in a TAL program. Table 1-2. NonStop SQL Directives Type Data Declaration Data Control Error Checking Directive BEGIN DECLARE SECTION, END DECLARE SECTION, INCLUDE SQLCA, INCLUDE SQLDA, INCLUDE SQLSA CONTROL EXECUTOR, CONTROL QUERY, CONTROL TABLE WHENEVER For more information, see Section 3, NonStop SQL Statements and Directives Declaring Host Variables A host variable provides communication between TAL statements and SQL statements in a program. A host variable is a TAL variable with a data type that corresponds to an SQL data type. You use host variables in SQL statements to receive data from a database and to insert data into a database. When you use a host variable with an SQL statement, you precede the host variable name with a colon (:). You declare host variables in a Declare Section with the TAL variable declarations. A Declare Section begins with the BEGIN DECLARE SECTION directive and ends with the END DECLARE SECTION directive. In this example, FILE^NUMBER and MESSAGE are host variables.! TAL declarations... EXEC SQL BEGIN DECLARE SECTION; INT file^number;! SQL host variables STRING.message[80] ; EXEC SQL END DECLARE SECTION;...! More TAL declarations... For more information, see Section 2, Host Variables and Parameters. Calling SQL System Procedures Use the provided TAL system library procedures to perform various SQL operations and functions. For example, the SQLCADISPLAY procedure returns error and statistics information after an SQL statement executes. A TAL program can call SQL system procedures in the same manner that it might call other system procedures such as OPEN, READ, WRITEREAD, and CLOSE. The $SYSTEM.SYSTEM.EXTDECS file contains source declarations of these procedures 1-3

26 Introduction Using Static SQL Statements that you can include in your program. This example shows a call to the SQLCADISPLAY procedure using all default parameters.?source $SYSTEM.SYSTEM.EXTDECS (SQLCADISPLAY)... CALL SQLCADISPLAY (SQLCA);! Process errors or statistics from the SQLCA structure... For more information, see Section 4, System Procedures. Using Static SQL Statements You can embed static SQL statements in both TAL data declarations and TAL executable statements. Figure 1-1 on page 1-5 shows an example of static SQL statements embedded in a TAL program. In this example, the program inserts a row in the PARTS table, which has the columns PARTNUM, PRICE, and PARTDESC. This example also declares data items as host variables so that they can contain input values for the columns of the row. 1-4

27 Introduction Using Dynamic SQL Operations Figure 1-1. Static SQL Statements in a TAL Program! TAL variable declarations: EXEC SQL BEGIN DECLARE SECTION;! SQL host variable declarations STRUCT.in^parts^rec; BEGIN INT in^partnum; FIXED(2) in^price; STRING in^partdesc[0:17]; END; EXEC SQL END DECLARE SECTION;...! Procedure Code: in^parts^rec.in^partnum := 4120; in^parts^rec.in^price := F;! Blank fill in^partdesc: in^parts^rec.in^partdesc ':=' [ $OCCURS(in^parts^rec.in^partdesc) * [" "] ]; in^parts^rec.in^partdesc ':=' "V8 DISK OPTION"; EXEC SQL INSERT INTO SALES.PARTS ( PARTNUM, PRICE, PARTDESC) VALUES (:in^parts^rec.in^partnum, :in^parts^rec.in^price, :in^parts^rec.in^partdesc);... VST0101.vsd For other examples of static SQL programming, see Section B, Examples of Static NonStop SQL Programs. Using Dynamic SQL Operations A dynamic SQL operation enables a TAL program to construct, compile, and execute an SQL statement at run time. With a static SQL operation, you code the SQL statement to be executed in the source file; however, with a dynamic SQL operation, you code only the host variable that will contain the SQL statement. A dynamic SQL operation requires some input, usually from a user at a terminal, to construct the final statement. The SQL statement is constructed from the user s input, compiled by the SQL compiler, and then executed using an EXECUTE or EXECUTE IMMEDIATE statement. 1-5

28 Introduction Using Dynamic SQL Operations Figure 1-2 shows a dynamic SQL operation that uses an INSERT statement similar to the static INSERT statement in Figure 1-1 on page 1-5. In Figure 1-1 on page 1-5, the static INSERT statement is embedded in the source program code; however, in Figure 1-2, the program dynamically builds the INSERT statement from information entered by a user. The program in Figure 1-2 accesses the PARTS table, which has the same file name, but resides on a different subvolume. When this program runs, it prompts a user for information to build the INSERT statement. The user enters this information in the INTEXT variable to specify the specific PARTS table and other values needed to construct the INSERT statement: INSERT INTO $vol5.sales.parts partnum, price, partdesc) VALUES (4120, , "V8 DISK OPTION") The program builds the INSERT statement from the information in INTEXT and moves the statement to the host variable OPERATION. The program has declared OPERATION as a host variable, so that it is available to both TAL and SQL statements. The program then uses the EXECUTE IMMEDIATE to execute the INSERT statement in OPERATION. Figure 1-2. Dynamic SQL Statements in a TAL Program! TAL data declarations EXEC SQL BEGIN DECLARE SECTION; STRING operation[0:199];! Host variable EXEC SQL END DECLARE SECTION;! TAL procedure! Copy intext into :operation host variable...! Execute the SQL statement: EXEC SQL EXECUTE IMMEDIATE :operation;... VST0102.vsd For more information, see Section 7, Dynamic NonStop SQL Operations and Section C, Examples of Dynamic NonStop SQL Programs. 1-6

29 Introduction Compiling and Executing a Program Compiling and Executing a Program Compiling and executing a TAL program that contains embedded SQL statements is similar to the steps you use for a TAL program that does not contain embedded SQL statements. You must perform only one extra step: you compile the SQL statements using the SQL compiler. These steps are shown in Figure Compile your source file (or files) using the TAL compiler. The TAL compiler generates an object file for each compilation. Each object file contains TAL object code and SQL source statements. 2. Use the Binder program, if necessary, to combine multiple object files into one object file or to specify the TALLIB run-time library if you did not include it during the TAL compilation in Step Optionally, run the Accelerator on the object file generated from Step 1 or 2 if you plan to run the object file on a TNS/R system. 4. Compile the SQL statements in the TAL object file using the SQL compiler. 5. Run the object file from a terminal using the TACL RUN (or RUND) command or from a process using a system procedure such as NEWPROCESS. 1-7

30 Introduction Compiling and Executing a Program Figure 1-3. Compiling and Executing a Program TAL/SQL Source File (s) 1 Run the TAL compiler for each source file TAL Compiler 2 Run the Binder program (if necessary) Binder Process 3 Run the Accelerator (optional step for TNS/R systems only) Accelerator 4 Run the SQL compiler 5 Run the object file SQL Compiler TAL/SQL Object File VST0103.vsd For more information, see Section 5, Program Compilation and Execution. 1-8

31 2 Host Variables and Parameters This section describes the data items that you use to provide for communication between TAL and SQL statements in a TAL program. Host Variables A host variable is a data item you can use in both TAL and SQL statements to provide for communication between the two types of statements. For static SQL operations, a host variable can be an input or output variable (or both in some cases) in SQL statements. An input variable transfers data from the program to the database, while an output variable transfers data from the database to the program. (For dynamic SQL operations, input parameters and output variables fulfill the same function as input and output host variables in static SQL statements.) A host variable can be a: Simple variable Whole STRING array (SQL type DECIMAL or CHAR) Element in an array Indirect array or structure (including standard and extended indirection) Structure that conforms to SQL data type VARCHAR Field in a structure SQLDA structure However, a host variable cannot be a: Constant TAL DEFINE identifier Variable of TAL data type UNSIGNED Pointer TAL array of type other than STRING Structure except VARCHAR and SQLDA structures A host variable can be any TAL data item that has a corresponding SQL data type as shown in Table 2-1 on page 2-3. NonStop SQL must be able to convert the data between the two data types. If your program returns a TAL assignment expression to a host variable, the TAL compiler must be able to convert the value of the expression to the data type of the host variable. 2-1

32 Host Variables and Parameters Declaring Host Variables Declaring Host Variables You declare host variables in a Declare Section in the variable declarations of your program. You can use multiple Declare Sections in a TAL program, but you cannot nest the sections. The SQL directives that delimit a Declare Section are BEGIN DECLARE SECTION and END DECLARE SECTION. Use TAL naming conventions for your host variables. Host variable names (and indicator variable names): Can contain from 1 to 31 alphanumeric characters including the circumflex (^) and the underscore (_) Must begin with a letter, circumflex, or underscore To prevent naming conflicts, avoid ending your names with an underscore. Examples of host variable declarations are: EXEC SQL BEGIN DECLARE SECTION;! host variables STRING.buffer[0:length]; INT number[0:9]; STRUCT.s^buffer; BEGIN INT buffer_length; STRING text[0:2046]; END; EXEC SQL END DECLARE SECTION; For information about using the INVOKE directive to create host variables, see Section 3, NonStop SQL Statements and Directives Using Corresponding SQL and TAL Data Types Table 2-1 on page 2-3 shows the corresponding NonStop SQL and TAL data types. If you have an SQL data type shown in the left column and you want to send data to a variable with that data type or receive data from a variable with that data type, declare a TAL host variable as shown in the right column. 2-2

33 Host Variables and Parameters Using Corresponding SQL and TAL Data Types Table 2-1. Corresponding NonStop SQL and TAL Data Types SQL Data Type Character Data CHAR(n), PIC X(n) VARCHAR(n) TAL Data Type STRING [0: n - 1] STRUCT identifier; BEGIN INT length; STRING value[0: n-1]; END; Numeric Data NUMERIC (1 to 4, s) SIGNED INT NUMERIC (1 to 4, s) UNSIGNED INT / SMALLINT UNSIGNED / 1 NUMERIC (5 to 9, s) SIGNED INT(32) NUMERIC (5 to 9, s) UNSIGNED INT(32) / INTEGER UNSIGNED/ 1 NUMERIC (10 to 18, s) SIGNED FIXED(s) PIC [s]9(n- s)v9(s) [COMP] Same as TAL data types for NUMERIC DECIMAL(n, s) STRING[0: n-1] / DECIMAL / 1 DECIMAL(n, s) UNSIGNED STRING[0: n-1] /DECIMAL UNSIGNED/ 1 PIC[s] 9(n- s)v9(s) SMALLINT INT SMALLINT UNSIGNED INT / SMALLINT UNSIGNED / 1 INTEGER INT(32) INTEGER UNSIGNED INT(32) / INTEGER UNSIGNED / 1 LARGEINT SIGNED FIXED(0) FLOAT (1 to 22), REAL REAL Date-Time Data DATETIME, TIMESTAMP, DATE, TIME STRING [0: n-1] INTERVAL Data INTERVAL STRING[0: n] 2 n is a positive integer that represents the length. For DECIMAL, n must range from 1 through 18. s is a positive integer that represents the scale of the number. 1 SQL data types between slashes specify override data type mapping (on page 2-4). 2 A host variable for an INTERVAL value has an extra byte to hold a sign. 2-3

34 Host Variables and Parameters Using Corresponding SQL and TAL Data Types Data Conversion NonStop SQL performs the conversion from SQL data types to TAL data types and from TAL data types to SQL data types as follows: When a host variable serves as an input variable (supplies a value to the database), the system first converts the value that the variable contains to a compatible SQL data type and then uses the value in the SQL operation. When a host variable serves as an output variable (receives a value from a database), the system converts the value to the data type of the host variable. NonStop SQL supports conversion within character types and numeric types, but it does not support conversion between character and numeric types. The SQL date-time and INTERVAL types are compatible only with TAL STRING types (and the STRING host variable used to store the date-time or INTERVAL value must have a TYPE AS clause). For more information, see Using Date-Time and INTERVAL Data Types as Host Variables on page For conversion between character strings of different lengths, NonStop SQL pads the receiving string on the right with blanks as necessary. If the receiving string is too short, NonStop SQL truncates the right part of the longer string and returns a warning code in the SQLCODE variable. If an input value is too large for an SQL column, NonStop SQL returns error 8300 (filesystem error encountered). If you are using the SQLCADISPLAY procedure to obtain an error message, SQLCADISPLAY also returns file-system error number For conversion between numeric types, NonStop SQL converts data between signed and unsigned types and between types with different precisions. You can use the SETSCALE function to communicate a number s scale to and from a database. Examples of host variable declarations using the default data types are: EXEC SQL BEGIN DECLARE SECTION;! SQL recognizes address as a SMALLINT host variable INT address;! SQL recognizes name as a CHAR(20) host variable STRING.name[0:19];!SQL recognizes message as a VARCHAR(200) host variable STRUCT.message; BEGIN INT msg^length; STRING text[0:199]; END; EXEC SQL END DECLARE SECTION; 2-4

35 Host Variables and Parameters Overriding Default Data Types Overriding Default Data Types Each TAL data type has a default SQL data type used by the SQL compiler. In most cases, you can define your host variables to match the SQL data types shown in Table 2-1 on page 2-3. Sometimes, however, you might want to use another data type. Some TAL data types allow you to override the default type by specifying an override SQL data type as an attribute of the host variable. The syntax to override a data type is: TAL-type hostvar-name [array-bounds] [/ override-sql-type/] TAL-type is the TAL data type plus any indirection symbol. For example: INT INT(32) INT. INT.EXT hostvar-name is the name of the host variable. array-bounds is the bounds of an array. For example, in the declaration: INT numbers[0:19]; [0:19] is the bounds. override-sql-type is the SQL data type that will override the default type that NonStop SQL normally uses for TAL-type. Specify override-sql-type after the host variable and any array bounds but before initialization or address equivalence takes place. Also, when you use a host variable in an SQL statement, you can override character data types by using the: TYPE AS clause to specify that the character string should be interpreted as a date-time value. The TYPE AS clause is described under Using Date-Time and INTERVAL Data Types as Host Variables on page SETSCALE function to indicate that an integer host variable is to be interpreted as having scale. SETSCALE is described under Using Scaled Numeric Data Items as Host Variables on page Table 2-2 shows how NonStop SQL interprets TAL data types, and the override data types you can specify. 2-5

36 Host Variables and Parameters Using Host Variables Table 2-2. Default and Override Data Type Mapping TAL Data Type Default SQL Data Type Override SQL Data Type STRING CHAR(1) / DECIMAL(1) / / DECIMAL(1) UNSIGNED / STRING[0: n-1] CHAR(n) / DECIMAL(n) / * / DECIMAL(n) UNSIGNED / * INT SMALLINT / SMALLINT UNSIGNED / INT(32) INTEGER / INTEGER UNSIGNED / FIXED(0) LARGEINT - FIXED(s) LARGEINT(s) ** - REAL REAL - REAL(64) DOUBLE PRECISION - STRUCT SQLDA VARCHAR(n) *** - n is a positive integer that represents the length. s is a positive integer that represents the scale of the number. * For DECIMAL types, n must be in the range 1 through 18. ** LARGEINT(s) type is used internally to SQL, but it is not an SQL type. *** The default is the SQLDA unless the structure conforms to type VARCHAR (see Table 2-1 on page 2-3). Examples of overriding default data type mapping are: EXEC SQL BEGIN DECLARE SECTION;! SQL recognizes empid as a DECIMAL(10) host variable STRING.empid[0:9]/DECIMAL(10)/;! SQL recognizes partnum as a SMALLINT UNSIGNED host variable INT partnum /SMALLINT UNSIGNED/;! SQL recognizes size as an INTEGER UNSIGNED host variable INT(32) size /INTEGER UNSIGNED/; EXEC SQL END DECLARE SECTION; Using Host Variables After you declare a host variable, you can use the variable in an SQL statement just as you would in a TAL statement, except that you must precede the host variable name with a colon(:). The colon causes the TAL compiler to treat the name as a host 2-6

37 Host Variables and Parameters Using Host Variables variable. The syntax for using a host variable in an SQL statement is shown below. For a complete description of this syntax, see the SQL/MP Reference Manual. :host-identifier[[ INDICATOR ]: indicator-host-identifier ] [ TYPE AS {DATETIME [start-date-time TO] end-date-time } ] [ { } ] [ {DATE } ] [ { } ] [ {TIME } ] [ { } ] [ {TIMESTAMP } ] [ { } ] [ {INTERVAL start-date-time } ] [ { [ ( start-field-precision ) ] } ] [ { [ TO end-date-time ] } ] :host-identifier is a TAL data item. Use :host-identifier in DML statements where a literal can be used (except in the INVOKE and INCLUDE directives). INDICATOR is a keyword that allows for: Handling null values that might be returned to the host variable Inserting null values into the database through the host variable :indicator-host-identifier is an indicator variable with type INT. For values returned to a host variable, : indicator-host-identifier is: -1 if the value is null 0 if the value is not null To insert t null values into the database, set : indicator-host-identifier to a value less than zero. TYPE AS directs NonStop SQL to treat the variable as a date-time (DATETIME, DATE, TIME, or TIMESTAMP) or INTERVAL value. To direct NonStop SQL to treat the host variable as a scaled value, either define the variable as TAL data type FIXED or use the SETSCALE function, which is described under Using Scaled Numeric Data Items as Host Variables on page

38 Host Variables and Parameters Using Host Variables Using Structures as Host Variables Follow the guidelines below when you declare and use structures or fields within structures as host variables. INVOKE Directive. Use the INVOKE directive to declare structure descriptions corresponding to SQL tables and views. The structure fields (which correspond to the columns in the table or view) become host variables. For information about using the INVOKE directive to create host variables, see Creating Host Variables With the INVOKE Directive on page VARCHAR Type. Declare host variables that correspond to the SQL VARCHAR type as TAL structures. See Table 2-1 on page 2-3 for an example of the TAL structure. For these structures, you can refer to both the TAL structure name and the individual fields; however, only the structure name is recognized as a host variable of SQL type VARCHAR. Structure Name References. You can refer to a structure name as a host variable only if the structure: Represents an item of SQL type VARCHAR Is an SQLDA Has an array of type STRING as its only field For other TAL structures, you can refer to only the individual fields in the structure as host variables, but you cannot refer to the structure name. Except for the above cases, you must use the structure name with the field name to reference a host variable that is a field within a structure. For example, the structure named EMPLOYEE^INFO contains the EMPID, EMPNAME, and SALARY host variables. EXEC SQL BEGIN DECLARE SECTION; STRUCT.employee^info; BEGIN STRING empid[0:9]; STRING empname[0:19]; FIXED(2) salary; END; EXEC SQL END DECLARE SECTION; When you use these host variables in an SQL statement, refer to them by the structure and field names. For example: EXEC SQL SELECT empid, empname, salary INTO :employee^info.empid, :employee^info.empname, :employee^info.salary FROM =employee WHERE empid = 12345; 2-8

39 Host Variables and Parameters Using Host Variables Structure Pointers. Although you cannot use a pointer by itself as a host variable, you can refer to a field in a structure by using a structure pointer. For example, you can use this host variable declaration and reference:! Declaration: EXEC SQL BEGIN DECLARE SECTION; STRUCT s^template(*); BEGIN INT field1;! Fields cannot be pointers in SQL INT field2; END; STRING.EXT s^ptr (s^template);! Structure pointer EXEC SQL END DECLARE SECTION;! Reference: EXEC SQL SELECT col1 INTO :s^ptr.field1 FROM tbl1; You can also use a structure as a host variable by: Using array indexing within the structure Allowing a field in the structure to be a substructure or an array These examples show TAL structures that you can use as host variables:! Substructures and array within a structure: STRUCT.outer^struct;! Structure BEGIN INT int^array[0:4];! Array STRUCT sub^struct^1;! Substructure BEGIN STRUCT sub^struct^2;! Substructure BEGIN INT int^1; INT int^2; END; END; END;! A three-dimensional structure of VARCHAR items: STRUCT.first^dim[0:3]; BEGIN; STRUCT second^dim[0:3]; BEGIN STRUCT third^dim[0:3]; BEGIN INT len; STRING name[0:19]; END; END; END; 2-9