HP NonStop SQL/MX Release 3.2.1 Programming Manual for C and COBOL Abstract This manual explains how to use embedded SQL for HP NonStop™ SQL/MX for C, C++, and COBOL. In NonStop SQL/MX, a C, C++, or COBOL program uses embedded SQL/MX statements to access HP NonStop SQL/MP and SQL/MX databases. Product Version NonStop SQL/MX Release 3.2.1 Supported Release Version Updates (RVUs) This publication supports J06.14 and all subsequent J-series RVUs and H06.25 and all subsequent H-series RVUs, until otherwise indicated by its replacement publications. Part Number Published 663854-005 June 2013 Document History Part Number Product Version Published 544617-002 NonStop SQL/MX Release 2.3 February 2010 544617-003 NonStop SQL/MX Release 2.3 August 2010 663854-001 NonStop SQL/MX Release 3.1 October 2011 663854-002 NonStop SQL/MX Release 3.2 August 2012 663854-004 NonStop SQL/MX Release 3.2.1 February 2013 663854-005 NonStop SQL/MX Release 3.2.1 June 2013 Legal Notices Copyright 2013 Hewlett-Packard Development Company L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Export of the information contained in this publication may require authorization from the U.S. Department of Commerce. Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation. Intel, Itanium, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks and IT DialTone and The Open Group are trademarks of The Open Group in the U.S. and other countries. Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. OSF shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material. © 1990, 1991, 1992, 1993 Open Software Foundation, Inc. This documentation and the software to which it relates are derived in part from materials supplied by the following: © 1987, 1988, 1989 Carnegie-Mellon University. © 1989, 1990, 1991 Digital Equipment Corporation. © 1985, 1988, 1989, 1990 Encore Computer Corporation. © 1988 Free Software Foundation, Inc. © 1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. © 1985, 1987, 1988, 1989, 1990, 1991, 1992 International Business Machines Corporation. © 1988, 1989 Massachusetts Institute of Technology. © 1988, 1989, 1990 Mentat Inc. © 1988 Microsoft Corporation. © 1987, 1988, 1989, 1990, 1991, 1992 SecureWare, Inc. © 1990, 1991 Siemens Nixdorf Informationssysteme AG. © 1986, 1989, 1996, 1997 Sun Microsystems, Inc. © 1989, 1990, 1991 Transarc Corporation. This software and documentation are based in part on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. OSF acknowledges the following individuals and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. © 1980, 1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California. Printed in the US HP NonStop SQL/MX Release 3.2.1 Programming Manual for C and COBOL Index Examples Figures Tables Legal Notices What’s New in This Manual xv Manual Information xv New and Changed Information xv About This Manual xix Audience xix Organization xix Related Documentation xx Examples in This Manual xxiii Notation Conventions xxiii Change Bar Notation xxvi HP Encourages Your Comments xxvi 1. Introduction Referencing Database Object Names 1-1 NonStop SQL/MX Release 2.x 1-1 NonStop SQL/MX Release 1.x 1-1 Embedding SQL Statements 1-2 Embedding SQL Statements in DLL 1-2 Declaring and Using Host Variables 1-3 Declaring Host Variables 1-3 Using Host Variables 1-4 Using DML Statements to Manipulate Data 1-4 Declaring and Using Static SQL Cursors 1-5 Using Dynamic SQL 1-7 Using Descriptor Areas for Dynamic SQL 1-7 Using Dynamic SQL Cursors 1-8 Using DML Statements With Rowsets 1-8 Improving Performance by Using Rowsets 1-8 Declaring a Rowset 1-9 Using a Rowset in a Query 1-9 Hewlett-Packard Company—663854-005 i Contents 2. Embedded SQL Statements Processing Exception Conditions 1-10 Checking SQLSTATE 1-10 Using WHENEVER 1-10 Using GET DIAGNOSTICS 1-11 Ensuring Data Consistency 1-11 Compiling and Building an Application 1-12 Processing With Embedded Module Definitions 1-12 Processing With Module Definition Files 1-12 General Instructions 1-13 SQL/MX Host Language Preprocessor 1-13 SQL/MX Compiler 1-14 Host Language Compiler 1-14 Program and Module Management 1-14 2. Embedded SQL Statements Syntax for Coding SQL Statements 2-1 Guidelines for Coding SQL Statements 2-1 Placement of SQL Statements 2-2 MODULE Directive 2-2 Host Variable Declarations 2-2 Nonexecutable SQL Statements 2-4 Executable SQL Statements 2-4 Embedded SQL Declarations and Statements 2-6 Considerations for Embedding DDL and DML Statements 2-12 Considerations for Embedding the UPDATE STATISTICS Statement 2-12 Using CONTROL Statements 2-12 ANSI Compliance and Portability 2-13 Static and Dynamic CONTROL Statements 2-13 CONTROL, Line Order Scope, and Static SQL programs 2-13 CONTROL, Flow Control Scope, and Dynamic SQL programs 2-13 3. Host Variables in C/C++ Programs Specifying a Declare Section 3-1 C Host Variable Data Types 3-2 Character Host Variables 3-3 Date-Time and Interval Host Variables 3-4 Numeric Host Variables 3-6 Floating-Point Host Variables 3-7 Using Corresponding SQL and C Data Types 3-8 Extended Host Variable Data Types and Generated C Data Types 3-11 HP NonStop SQL/MX Release 3.2.1 Programming Manual for C and COBOL—663854-005 ii Contents 4. Host Variables in COBOL Programs Data Conversion 3-13 Specifying Host Variables in SQL Statements 3-15 Using Host Variables in a C/C++ Program 3-16 Character Set Data 3-16 Fixed-Length Character Data 3-17 Variable-Length Character Data 3-19 Numeric Data 3-22 Date-Time and Interval Data 3-33 Host Variables in C Structures 3-39 Host Variables as Data Members of a C++ Class 3-39 Using Indicator Variables in a C/C++ Program 3-40 Inserting Null 3-40 Testing for Null or a Truncated Value 3-41 Retrieving Rows With Nulls 3-41 Creating C Host Variables Using INVOKE 3-42 Using the INVOKE Directive 3-42 INVOKE and Date-Time and Interval Host Variables (SQL/MX Release 1.8 Applications) 3-43 INVOKE and Floating-Point Host Variables 3-44 C Data Types Generated by INVOKE 3-45 Using Indicator Variables With the INVOKE Directive 3-48 C Example of Using INVOKE 3-50 Character Set Examples 3-51 Selecting From a UCS2 Character Set Into a VARCHAR Host Variable 3-52 Fetching From a UCS2 Character Set into a VARCHAR Host Variable 3-52 Selecting From an ISO88591 Character Set Into a UCS2 Host Variable 3-53 4. Host Variables in COBOL Programs Specifying a Declare Section 4-1 COBOL Host Variable Data Types 4-2 Using Corresponding SQL and COBOL Data Types 4-5 Data Conversion 4-8 Specifying Host Variables in SQL Statements 4-9 Using Host Variables in a COBOL Program 4-10 Character Set Data 4-10 Fixed-Length Character Data 4-11 Variable-Length Character Data 4-12 Numeric Data 4-12 Date-Time and Interval Data 4-13 HP NonStop SQL/MX Release 3.2.1 Programming Manual for C and COBOL—663854-005 iii Contents 5. Simple and Compound Statements Using COBOL Data Description Clauses 4-18 Using Indicator Variables in a COBOL Program 4-19 Inserting Null 4-19 Testing for Null or a Truncated Value 4-20 Retrieving Rows With Nulls 4-21 Creating COBOL Host Variables Using INVOKE 4-22 Using the INVOKE Directive 4-23 INVOKE and Date-Time and Interval Host Variables (SQL/MX Release 1.8 Applications) 4-23 COBOL Record Descriptions Generated by INVOKE 4-23 Using Indicator Variables With the INVOKE Directive 4-27 COBOL Example of Using INVOKE 4-29 Character Set Examples 4-30 Selecting From a UCS2 Character Set Into a VARCHAR Host Variable 4-31 Fetching From a UCS2 Character Set into a VARCHAR Host Variable 4-31 5. Simple and Compound Statements Single-Row SELECT Statement 5-2 Using a Primary Key Value to Select Data 5-2 Selecting a Column With Date-Time or INTERVAL Data Type 5-3 INSERT Statement 5-4 Inserting Rows 5-5 Inserting Null 5-6 Inserting a Date-Time Value 5-7 Inserting an Interval Value 5-8 Searched UPDATE Statement 5-9 Updating a Single Row 5-10 Updating Multiple Rows 5-11 Updating Columns To Null 5-11 Searched DELETE Statement 5-12 Deleting a Single Row 5-12 Deleting Multiple Rows 5-12 Compound Statements 5-13 Assignment Statement 5-15 IF Statement 5-16 Using PROTOTYPE Host Variables as Table Names 5-17 6.