-
IBM Informix
IBM Informix ESQL/C Programmer’s Manual
Version 3.50
SC23-9420-04
���
-
IBM Informix
IBM Informix ESQL/C Programmer’s Manual
Version 3.50
SC23-9420-04
���
-
Note:Before using this information and the product it supports,
read the information in “Notices” on page E-1.
This edition replaces SC23-9420-03.
This document contains proprietary information of IBM. It is
provided under a license agreement and is protectedby copyright
law. The information contained in this publication does not include
any product warranties, and anystatements provided in this manual
should not be interpreted as such.
When you send information to IBM, you grant IBM a nonexclusive
right to use or distribute the information in anyway it believes
appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1996,
2009.US Government Users Restricted Rights – Use, duplication or
disclosure restricted by GSA ADP Schedule Contractwith IBM
Corp.
-
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . xvIn this Introduction. . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . xvAbout This Publication . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Types of Users . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . xvSoftware Dependencies . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . xviAssumptions About Your Locale .
. . . . . . . . . . . . . . . . . . . . . . . . . .
xviDemonstration Databases . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . xvi
What’s New in ESQL/C for Client SDK . . . . . . . . . . . . . .
. . . . . . . . . . . xviiDocumentation Conventions . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . xvii
Technical Changes . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . xviiFeature, Product, and Platform Markup . . . . .
. . . . . . . . . . . . . . . . . . . xviiExample Code Conventions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Additional Documentation . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . xviiiCompliance with Industry Standards . . . . .
. . . . . . . . . . . . . . . . . . . . . xixSyntax Diagrams . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
How to Read a Command-Line Syntax Diagram . . . . . . . . . . .
. . . . . . . . . . . xxKeywords and Punctuation . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . xxiIdentifiers and Names .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
How to Provide Documentation Feedback. . . . . . . . . . . . . .
. . . . . . . . . . . xxii
Part 1. What Is IBM Informix ESQL/C?
Chapter 1. Programming with IBM Informix ESQL/C . . . . . . . .
. . . . . . . . 1-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 1-2What Is IBM Informix ESQL/C?
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
ESQL/C Components. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 1-2Creating an ESQL/C Program . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 1-4
Embedding SQL Statements. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 1-4Handling Case Sensitivity in Embedded SQL
Statements . . . . . . . . . . . . . . . . . . . 1-5Using Quotes
and Escape Characters . . . . . . . . . . . . . . . . . . . . . . .
. . 1-6Adding Comments . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 1-8Specifying Host Variables . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 1-8
Declaring and Using Host Variables . . . . . . . . . . . . . . .
. . . . . . . . . . . . 1-9Declaring a Host Variable . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 1-10Assigning a Value
to a Host Variable . . . . . . . . . . . . . . . . . . . . . . . .
. 1-13Using Host Variables in Data Structures . . . . . . . . . . .
. . . . . . . . . . . . . 1-16Using Host Variables in Windows
Environments (Windows) . . . . . . . . . . . . . . . . . 1-20Using
Indicator Variables . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 1-22
Using ESQL/C Header Files . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 1-25Declaring Function Prototypes . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1-27Including Header Files
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-28
Using ESQL/C Preprocessor Directives . . . . . . . . . . . . . .
. . . . . . . . . . . 1-28The include Directive . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1-29The define and undef
Directives . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-30The ifdef, ifndef, elif, else, and endif Directives . . . . . .
. . . . . . . . . . . . . . . . 1-31
Setting and Retrieving Environment Variables in Windows
Environments (Windows) . . . . . . . . . . 1-32InetLogin Structure
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-33
Using Global ESQL/C Variables in a Windows Environment . . . . .
. . . . . . . . . . . . . 1-39A Sample IBM Informix ESQL/C Program
. . . . . . . . . . . . . . . . . . . . . . . . 1-39
Compiling the demo1 Program . . . . . . . . . . . . . . . . . .
. . . . . . . . . 1-39Guide to demo1.ec File . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 1-40
Chapter 2. Compiling Programs. . . . . . . . . . . . . . . . . .
. . . . . . . 2-1In This Chapter . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 2-2
© Copyright IBM Corp. 1996, 2009 iii
-
Compiling an IBM Informix ESQL/C Program . . . . . . . . . . . .
. . . . . . . . . . . 2-2ESQL/C Preprocessor. . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 2-2C Preprocessor and
Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-3Default Compilation Order . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 2-4Running the C Preprocessor First . . . . . .
. . . . . . . . . . . . . . . . . . . . . 2-4
Using the esql Command . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 2-5Requirements for Using esql . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 2-5Syntax of the esql Command
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Options
That Affect Preprocessing . . . . . . . . . . . . . . . . . . . . .
. . . . . 2-12Running the C Preprocessor Before the ESQL/C
Preprocessor . . . . . . . . . . . . . . . . . 2-17Preprocessor
Options Specific to Windows Environments . . . . . . . . . . . . .
. . . . . 2-23
Compiling and Linking Options of the esql Command . . . . . . .
. . . . . . . . . . . . . 2-24Naming the Executable . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 2-24Setting the Type of
Executable Created (Windows). . . . . . . . . . . . . . . . . . . .
. 2-24Passing Options to the C Compiler . . . . . . . . . . . . . .
. . . . . . . . . . . . 2-24Specifying a Particular C Compiler
(Windows) . . . . . . . . . . . . . . . . . . . . . . 2-25Compiling
Without Linking . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 2-25Special Compile Options for Windows Environments . . . . .
. . . . . . . . . . . . . . . 2-25Linking Options . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 2-28
Accessing the ESQL Client-Interface DLL in Windows Environments
. . . . . . . . . . . . . . . 2-31Accessing the Import Library . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 2-31Locating a
DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-32Building an Application DLL . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 2-32
Chapter 3. Informix ESQL/C Data Types . . . . . . . . . . . . .
. . . . . . . . 3-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 3-1Choosing Data Types for Host
Variables . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Data Type Constants . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 3-3Header Files for Data Types . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 3-7
Data Conversion . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 3-8Fetching and Inserting with Host Variables . .
. . . . . . . . . . . . . . . . . . . . . 3-9Performing Arithmetic
Operations . . . . . . . . . . . . . . . . . . . . . . . . . .
3-11
Data-Type Alignment Library Functions . . . . . . . . . . . . .
. . . . . . . . . . . . 3-13
Chapter 4. Working with Character and String Data Types . . . .
. . . . . . . . . 4-1In This Chapter . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 4-1Character Data Types . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
The char Data Type . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 4-2The fixchar Data Type . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 4-2The string Data Type . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 4-3The varchar
Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 4-3The lvarchar Data Type . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 4-5
Fetching and Inserting Character Data Types . . . . . . . . . .
. . . . . . . . . . . . . . 4-7Fetching and Inserting CHAR Data . .
. . . . . . . . . . . . . . . . . . . . . . . . 4-7Fetching and
Inserting VARCHAR Data . . . . . . . . . . . . . . . . . . . . . .
. . 4-8Fetching and Inserting lvarchar Data . . . . . . . . . . . .
. . . . . . . . . . . . . 4-11Fetching and Inserting with an
ANSI-Compliant Database . . . . . . . . . . . . . . . . . .
4-12
Character and String Library Functions . . . . . . . . . . . . .
. . . . . . . . . . . . 4-12
Chapter 5. Working with Numeric Data Types . . . . . . . . . . .
. . . . . . . . 5-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 5-1The Integer Data Types . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
The Integer Host Variable Types . . . . . . . . . . . . . . . .
. . . . . . . . . . . 5-2The INT8 and SERIAL8 SQL Data Types . . .
. . . . . . . . . . . . . . . . . . . . . 5-2The int8 Data Type . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2The
int8 Library Functions . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 5-3
The BOOLEAN Data Type . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 5-4The Decimal Data Type . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 5-5
The decimal Structure. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 5-5The decimal Library Functions. . . . . . . . .
. . . . . . . . . . . . . . . . . . . 5-7
iv IBM Informix ESQL/C Programmer’s Manual
-
The Floating-Point Data Types . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 5-8Declaring float Host Variables . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 5-8Implicit Data
Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 5-8
Formatting Numeric Strings . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 5-9Numeric-Formatting Functions . . . . . . . .
. . . . . . . . . . . . . . . . . . . 5-13
Chapter 6. Working with Time Data Types . . . . . . . . . . . .
. . . . . . . . 6-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 6-1The SQL DATE Data Type . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Formatting Date Strings . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 6-1DATE Library Functions . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 6-2The SQL DATETIME and
INTERVAL Data Types . . . . . . . . . . . . . . . . . . . . . .
6-2
The datetime Data Type . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 6-4The interval Data Type . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 6-4Macros for datetime and
interval Data Types . . . . . . . . . . . . . . . . . . . . . . .
6-5Fetching and Inserting DATETIME and INTERVAL Values . . . . . .
. . . . . . . . . . . . 6-6ANSI SQL Standards for DATETIME and
INTERVAL Values. . . . . . . . . . . . . . . . . . 6-7Data
Conversion for datetime and interval Values . . . . . . . . . . . .
. . . . . . . . . 6-8
Support of Non-ANSI DATETIME Formats . . . . . . . . . . . . . .
. . . . . . . . . . 6-8The USE_DTENV environment variable. . . . .
. . . . . . . . . . . . . . . . . . . . 6-8
DATETIME and INTERVAL Library Functions . . . . . . . . . . . .
. . . . . . . . . . . 6-9
Chapter 7. Working with Simple Large Objects . . . . . . . . . .
. . . . . . . . 7-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 7-2Choosing a Large-Object Data
Type (IDS) . . . . . . . . . . . . . . . . . . . . . . . . .
7-2Programming with Simple Large Objects . . . . . . . . . . . . .
. . . . . . . . . . . . 7-3
Declaring a Host Variable for a Simple Large Object . . . . . .
. . . . . . . . . . . . . . 7-3Accessing the Locator Structure . .
. . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Locating Simple Large Objects in Memory . . . . . . . . . . . .
. . . . . . . . . . . . . 7-7Allocating the Memory Buffer . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 7-8Selecting a Simple
Large Object into Memory . . . . . . . . . . . . . . . . . . . . .
. 7-10Inserting a Simple Large Object from Memory . . . . . . . . .
. . . . . . . . . . . . . 7-11
Locating Simple Large Objects in Files . . . . . . . . . . . . .
. . . . . . . . . . . . . 7-13File-Open Mode Flags . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 7-13Error Returns in
loc_status. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-14Locating Simple Large Objects in Open Files. . . . . . . . . .
. . . . . . . . . . . . . 7-14Locating Simple Large Objects in
Named Files . . . . . . . . . . . . . . . . . . . . . . 7-18
Using User-Defined Simple-Large-Object Locations . . . . . . . .
. . . . . . . . . . . . . 7-22Selecting a Simple Large Object into
a User-Defined Location . . . . . . . . . . . . . . . . .
7-23Inserting a Simple Large Object into a User-Defined Location .
. . . . . . . . . . . . . . . . 7-23Creating the User-Defined
Simple-Large-Object Functions . . . . . . . . . . . . . . . . . .
7-24
Reading and Writing Simple Large Objects to an Optical Disc
(UNIX) . . . . . . . . . . . . . . . 7-28The dispcat_pic Program .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-31
Loading the Simple-Large-Object Images . . . . . . . . . . . . .
. . . . . . . . . . . 7-32Guide to the dispcat_pic.ec File . . . .
. . . . . . . . . . . . . . . . . . . . . . . 7-33Guide to the
prdesc.c File . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 7-41Guide to the inpfuncs.c File . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 7-42
Chapter 8. Working with Smart Large Objects (IDS) . . . . . . .
. . . . . . . . . 8-1In This Chapter . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 8-1Data Structures for Smart
Large Objects . . . . . . . . . . . . . . . . . . . . . . . . .
8-2
Declaring a Host Variable . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 8-2The LO-Specification Structure . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 8-3The LO-Pointer
Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8-9The LO-File Descriptor . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 8-11
Creating a Smart Large Object . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 8-12Accessing a Smart Large Object . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 8-12
Selecting a Smart Large Object . . . . . . . . . . . . . . . . .
. . . . . . . . . . 8-12Opening a Smart Large Object . . . . . . .
. . . . . . . . . . . . . . . . . . . . 8-13Deleting a Smart Large
Object . . . . . . . . . . . . . . . . . . . . . . . . . . .
8-17
Contents v
-
Modifying a Smart Large Object . . . . . . . . . . . . . . . . .
. . . . . . . . . . 8-17Closing a Smart Large Object . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 8-18
Obtaining the Status of a Smart Large Object . . . . . . . . . .
. . . . . . . . . . . . . 8-18Obtaining a Valid LO-Pointer
Structure . . . . . . . . . . . . . . . . . . . . . . . .
8-18Allocating and Accessing an LO-Status Structure . . . . . . . .
. . . . . . . . . . . . . 8-18Deallocating the LO-Status Structure
. . . . . . . . . . . . . . . . . . . . . . . . . 8-19
Altering a Smart-Large-Object Column . . . . . . . . . . . . . .
. . . . . . . . . . . 8-20Migrating Simple Large Objects . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 8-20Reading and
Writing Smart Large Objects on an Optical Disc (UNIX) . . . . . . .
. . . . . . . . 8-21The ESQL/C API for Smart Large Objects . . . .
. . . . . . . . . . . . . . . . . . . . 8-21
Chapter 9. Working with Complex Data Types (IDS) . . . . . . . .
. . . . . . . . 9-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 9-1Accessing a Collection . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Accessing a Collection Derived Table . . . . . . . . . . . . . .
. . . . . . . . . . . 9-2Declaring Collection Variables . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 9-4Managing Memory for
Collections . . . . . . . . . . . . . . . . . . . . . . . . . .
9-9Operating on a Collection Variable . . . . . . . . . . . . . . .
. . . . . . . . . . . 9-10Operating on a Collection Column . . . .
. . . . . . . . . . . . . . . . . . . . . . 9-28
Accessing Row Types . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 9-30Declaring Row Variables . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 9-31Managing Memory for Rows .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 9-35Operating
on a Row Variable . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 9-36Accessing a Typed Table . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 9-44Operating on a Row-Type Column . . . .
. . . . . . . . . . . . . . . . . . . . . . 9-44
Chapter 10. Working with Opaque Data Types (IDS) . . . . . . . .
. . . . . . . 10-1In This Chapter . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 10-1The SQL Opaque Data Type . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 10-1Accessing
the External Format of an Opaque Type. . . . . . . . . . . . . . .
. . . . . . . 10-3
Declaring lvarchar Host Variables . . . . . . . . . . . . . . .
. . . . . . . . . . . 10-4Using lvarchar Host Variables . . . . . .
. . . . . . . . . . . . . . . . . . . . . 10-7
Accessing the Internal Format of an Opaque Type . . . . . . . .
. . . . . . . . . . . . . 10-11Accessing a Fixed-Length Opaque Type
. . . . . . . . . . . . . . . . . . . . . . . . 10-12Accessing a
Varying-Length Opaque Type . . . . . . . . . . . . . . . . . . . .
. . . 10-15
The lvarchar pointer and var binary Library Functions . . . . .
. . . . . . . . . . . . . . . 10-22Accessing Predefined Opaque Data
Types . . . . . . . . . . . . . . . . . . . . . . . . 10-22
Part 2. Database Server Communication
Chapter 11. Exception Handling . . . . . . . . . . . . . . . . .
. . . . . . . 11-1In This Chapter . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 11-2Obtaining Diagnostic
Information After an SQL Statement . . . . . . . . . . . . . . . .
. . . 11-2
Types of Diagnostic Information . . . . . . . . . . . . . . . .
. . . . . . . . . . . 11-2Types of Status Variables . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 11-3
Exception Handling with SQLSTATE . . . . . . . . . . . . . . . .
. . . . . . . . . . 11-3Using GET DIAGNOSTICS . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 11-4Using the SQLSTATE Variable .
. . . . . . . . . . . . . . . . . . . . . . . . . . 11-7Checking
for Exceptions with SQLSTATE . . . . . . . . . . . . . . . . . . .
. . . . 11-11
Exception Handling with the sqlca Structure . . . . . . . . . .
. . . . . . . . . . . . . 11-17Fields of the sqlca Structure . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 11-17Using the
SQLCODE Variable . . . . . . . . . . . . . . . . . . . . . . . . .
. . 11-19Checking for Exceptions with sqlca . . . . . . . . . . . .
. . . . . . . . . . . . . 11-20Displaying Error Text (Windows) . .
. . . . . . . . . . . . . . . . . . . . . . . . 11-25
Choosing an Exception-Handling Strategy . . . . . . . . . . . .
. . . . . . . . . . . . 11-25Checking After Each SQL Statement . .
. . . . . . . . . . . . . . . . . . . . . . . 11-25The WHENEVER
Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11-28
Library Functions for Retrieving Error Messages . . . . . . . .
. . . . . . . . . . . . . . 11-29Displaying Error Text in a Windows
Environment . . . . . . . . . . . . . . . . . . . . 11-30
A Program That Uses Exception Handling . . . . . . . . . . . . .
. . . . . . . . . . . 11-30
vi IBM Informix ESQL/C Programmer’s Manual
-
Compiling the Program . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 11-30Guide to the getdiag.ec File . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 11-30Guide to the exp_chk.ec
File . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11-32
Chapter 12. Working with the Database Server. . . . . . . . . .
. . . . . . . . 12-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 12-2The Client-Server
Architecture of ESQL/C Applications . . . . . . . . . . . . . . . .
. . . . 12-2The Client-Server Connection . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 12-3
Sources of Connection Information on a UNIX Operating System . .
. . . . . . . . . . . . . . 12-4Sources of Connection Information
in a Windows Environment . . . . . . . . . . . . . . . .
12-5Connecting to a Database Server . . . . . . . . . . . . . . . .
. . . . . . . . . . 12-10Identifying the Database Server. . . . . .
. . . . . . . . . . . . . . . . . . . . . 12-16
Interacting with the Database Server . . . . . . . . . . . . . .
. . . . . . . . . . . . 12-18Determining Features of the Database
Server . . . . . . . . . . . . . . . . . . . . . . 12-18Switching
Between Multiple Database Connections . . . . . . . . . . . . . . .
. . . . . 12-19Identifying an Explicit Connection. . . . . . . . .
. . . . . . . . . . . . . . . . . 12-20Obtaining Available
Databases . . . . . . . . . . . . . . . . . . . . . . . . . . .
12-22Checking the Status of the Database Server . . . . . . . . . .
. . . . . . . . . . . . . 12-22Detaching from a Connection . . . .
. . . . . . . . . . . . . . . . . . . . . . . 12-22Interrupting an
SQL Request . . . . . . . . . . . . . . . . . . . . . . . . . . .
12-22Error Checking During Data Transfer . . . . . . . . . . . . .
. . . . . . . . . . . . 12-27Terminating a Connection . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 12-27
Optimized Message Transfers . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 12-27Restrictions on Optimized Message
Transfers . . . . . . . . . . . . . . . . . . . . . . 12-28Enabling
Optimized Message Transfers . . . . . . . . . . . . . . . . . . . .
. . . . 12-28Error Handling with Optimized Message Transfers . . .
. . . . . . . . . . . . . . . . . 12-30
Using Database Server Control Functions . . . . . . . . . . . .
. . . . . . . . . . . . 12-31The timeout Program . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 12-31
Compiling the Program . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 12-31Guide to the timeout.ec File . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 12-31Example Output . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 12-44
Using ESQL/C Connection Library Functions in a Windows
Environment . . . . . . . . . . . . . 12-46
Chapter 13. Using Informix Libraries . . . . . . . . . . . . . .
. . . . . . . . 13-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 13-1Choosing a Version of the
Informix General Libraries . . . . . . . . . . . . . . . . . . . .
. 13-2
The Informix General Libraries . . . . . . . . . . . . . . . . .
. . . . . . . . . . 13-2The esql Command . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 13-3Linking Static Informix
General Libraries . . . . . . . . . . . . . . . . . . . . . . . .
13-4Linking Shared Informix General Libraries . . . . . . . . . . .
. . . . . . . . . . . . 13-4Choosing Between Shared and Static
Library Versions . . . . . . . . . . . . . . . . . . . 13-6
Compatibility of Preexisting ESQL/C Applications with Current
Library Versions . . . . . . . . . . . 13-7Using the ifx_getversion
Utility (UNIX) . . . . . . . . . . . . . . . . . . . . . . . .
13-8Checking the API Version of a Library . . . . . . . . . . . . .
. . . . . . . . . . . . 13-8
Creating Thread-Safe ESQL/C Applications . . . . . . . . . . . .
. . . . . . . . . . . . 13-9Characteristics of Thread-Safe ESQL/C
Code . . . . . . . . . . . . . . . . . . . . . . 13-10Programming a
Thread-Safe ESQL/C Application . . . . . . . . . . . . . . . . . .
. . 13-11Linking Thread-Safe Libraries . . . . . . . . . . . . . .
. . . . . . . . . . . . . 13-17
Using ESQL/C Thread-Safe Decimal Functions . . . . . . . . . . .
. . . . . . . . . . . 13-19Context Threaded Optimization . . . . .
. . . . . . . . . . . . . . . . . . . . . . 13-19A Sample
Thread-Safe Program. . . . . . . . . . . . . . . . . . . . . . . .
. . . . 13-20
Source Listing . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 13-20Output . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 13-25
Creating a Dynamic Thread Library on UNIX Operating Systems . .
. . . . . . . . . . . . . . 13-25Data Types . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 13-27Registering the
Dynamic Thread Functions . . . . . . . . . . . . . . . . . . . . .
. . 13-30Setting the $THREADLIB Environment Variable . . . . . . .
. . . . . . . . . . . . . . 13-32Creating the Shared Library . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 13-32Compiling
with the -thread and -l Preprocessor Options . . . . . . . . . . .
. . . . . . . 13-33
Contents vii
||
-
Part 3. Dynamic SQL
Chapter 14. Using Dynamic SQL . . . . . . . . . . . . . . . . .
. . . . . . . 14-1In This Chapter . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 14-1Using Dynamic SQL . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Assembling and Preparing the SQL Statement . . . . . . . . . . .
. . . . . . . . . . . 14-2Executing the SQL Statement . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 14-6Freeing Resources . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Using a Database Cursor . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 14-8Receiving More Than One Row . . . . . . . .
. . . . . . . . . . . . . . . . . . . 14-8Sending More Than One Row
. . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10Naming
the Cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 14-10Optimizing Cursor Execution . . . . . . . . . . . . . .
. . . . . . . . . . . . . 14-11
The collect.ec Program. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 14-21Optimizing OPEN, FETCH, and CLOSE . . . .
. . . . . . . . . . . . . . . . . . . . . 14-22
Restrictions on OPTOFC (IDS/UD) . . . . . . . . . . . . . . . .
. . . . . . . . . 14-22Enabling the OPTOFC Feature . . . . . . . .
. . . . . . . . . . . . . . . . . . . 14-23
Using OPTOFC and Deferred-PREPARE Together . . . . . . . . . . .
. . . . . . . . . . 14-24SQL Statements That Are Known at Compile
Time . . . . . . . . . . . . . . . . . . . . . 14-25
Executing Non-SELECT Statements . . . . . . . . . . . . . . . .
. . . . . . . . . 14-25Executing SELECT Statements . . . . . . . .
. . . . . . . . . . . . . . . . . . . 14-26The lvarptr.ec Program .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
14-29Executing User-Defined Routines in IBM Informix Dynamic Server
(IDS/UD) . . . . . . . . . . . 14-30Executing Statements with Input
Parameters . . . . . . . . . . . . . . . . . . . . . . 14-34
SQL Statements That Are Not Known at Compile Time. . . . . . . .
. . . . . . . . . . . . 14-38
Chapter 15. Determining SQL Statements . . . . . . . . . . . . .
. . . . . . . 15-1In This Chapter . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 15-1Using Dynamic-Management
Structure . . . . . . . . . . . . . . . . . . . . . . . . .
15-1
A System-Descriptor Area . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 15-2An sqlda Structure . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 15-5
Using the DESCRIBE Statement . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 15-8Determining the Statement Type . . . . . .
. . . . . . . . . . . . . . . . . . . . . 15-9Determining the Data
Type of a Column . . . . . . . . . . . . . . . . . . . . . . .
15-13Determining Input Parameters (IDS) . . . . . . . . . . . . . .
. . . . . . . . . . . 15-15Checking for a WHERE Clause . . . . . .
. . . . . . . . . . . . . . . . . . . . . 15-15
Determining Statement Information at Runtime . . . . . . . . . .
. . . . . . . . . . . . 15-16Handling an Unknown Select List . . .
. . . . . . . . . . . . . . . . . . . . . . . 15-16Handling an
Unknown Column List . . . . . . . . . . . . . . . . . . . . . . . .
. 15-17Determining Unknown Input Parameters . . . . . . . . . . . .
. . . . . . . . . . . 15-17Determining Return Values Dynamically .
. . . . . . . . . . . . . . . . . . . . . . 15-18Handling
Statements That Contain User-Defined Data Types . . . . . . . . . .
. . . . . . . 15-19
Using a Fetch Array . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 15-23Allocating Memory for the Fetch Arrays . . .
. . . . . . . . . . . . . . . . . . . . . 15-30Obtaining Values
from Fetch Arrays . . . . . . . . . . . . . . . . . . . . . . . . .
15-34Freeing Memory for a Fetch Array. . . . . . . . . . . . . . .
. . . . . . . . . . . 15-36
Chapter 16. Using a System-Descriptor Area . . . . . . . . . . .
. . . . . . . 16-1In This Chapter . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 16-2Managing a System-Descriptor
Area . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Allocating Memory for a System-Descriptor Area . . . . . . . . .
. . . . . . . . . . . . 16-3Initializing the System-Descriptor Area
. . . . . . . . . . . . . . . . . . . . . . . . 16-4Assigning and
Obtaining Values from a System-Descriptor Area . . . . . . . . . .
. . . . . . 16-5Specifying Input Parameter Values . . . . . . . . .
. . . . . . . . . . . . . . . . . 16-7Putting Column Values into a
System-Descriptor Area . . . . . . . . . . . . . . . . . . .
16-7Freeing Memory Allocated to a System-Descriptor Area . . . . .
. . . . . . . . . . . . . . 16-8
Using a System-Descriptor Area . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 16-8Handling an Unknown Select List . . . . .
. . . . . . . . . . . . . . . . . . . . . . 16-9
Executing a SELECT That Returns Multiple Rows . . . . . . . . .
. . . . . . . . . . . 16-10Executing a Singleton SELECT . . . . . .
. . . . . . . . . . . . . . . . . . . . . 16-13
viii IBM Informix ESQL/C Programmer’s Manual
-
Handling Unknown Return Values . . . . . . . . . . . . . . . . .
. . . . . . . . . 16-14Executing a Noncursor Function . . . . . . .
. . . . . . . . . . . . . . . . . . . 16-14Executing a Cursor
Function. . . . . . . . . . . . . . . . . . . . . . . . . . . .
16-17
Handling an Unknown Column List . . . . . . . . . . . . . . . .
. . . . . . . . . . 16-18Executing a Simple Insert. . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 16-19Executing an INSERT
That Is Associated with a Cursor. . . . . . . . . . . . . . . . . .
. 16-22
Handling a Parameterized SELECT Statement . . . . . . . . . . .
. . . . . . . . . . . . 16-22Executing a Parameterized SELECT That
Returns Multiple Rows . . . . . . . . . . . . . . . 16-23Executing
a Parameterized Singleton SELECT . . . . . . . . . . . . . . . . .
. . . . . 16-27
Handling a Parameterized User-Defined Routine . . . . . . . . .
. . . . . . . . . . . . . 16-27Executing a Parameterized Function .
. . . . . . . . . . . . . . . . . . . . . . . . 16-27Executing a
Parameterized Procedure. . . . . . . . . . . . . . . . . . . . . .
. . . 16-28
Handling a Parameterized UPDATE or DELETE Statement . . . . . .
. . . . . . . . . . . . 16-28The dyn_sql Program . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 16-28
Compiling the Program . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 16-28Guide to the dyn_sql.ec File . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 16-29
Chapter 17. Using an sqlda Structure. . . . . . . . . . . . . .
. . . . . . . . 17-1In This Chapter . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 17-2Managing an sqlda Structure .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Defining an sqlda Structure . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 17-3Allocating Memory for the sqlda Structure .
. . . . . . . . . . . . . . . . . . . . . . 17-3Initializing the
sqlda Structure . . . . . . . . . . . . . . . . . . . . . . . . . .
. 17-4Allocating Memory for Column Data . . . . . . . . . . . . . .
. . . . . . . . . . . 17-6Assigning and Obtaining Values from an
sqlda Structure . . . . . . . . . . . . . . . . . . 17-8Specifying
Input Parameter Values . . . . . . . . . . . . . . . . . . . . . .
. . . . 17-8Putting Column Values into an sqlda Structure . . . . .
. . . . . . . . . . . . . . . . . 17-9Freeing Memory Allocated to
an sqlda Structure . . . . . . . . . . . . . . . . . . . . .
17-10
Using an sqlda Structure . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 17-10Handling an Unknown Select List . . . . .
. . . . . . . . . . . . . . . . . . . . . . 17-11
Executing a SELECT That Returns Multiple Rows . . . . . . . . .
. . . . . . . . . . . 17-11Executing a Singleton SELECT . . . . . .
. . . . . . . . . . . . . . . . . . . . . 17-16
Handling Unknown Return Values . . . . . . . . . . . . . . . . .
. . . . . . . . . 17-16Executing a Noncursor Function . . . . . . .
. . . . . . . . . . . . . . . . . . . 17-17Executing a Cursor
Function. . . . . . . . . . . . . . . . . . . . . . . . . . . .
17-17
Handling an Unknown Column List . . . . . . . . . . . . . . . .
. . . . . . . . . . 17-18Executing a Simple Insert. . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 17-19Executing an INSERT
That Is Associated with a Cursor. . . . . . . . . . . . . . . . . .
. 17-19
Handling a Parameterized SELECT Statement . . . . . . . . . . .
. . . . . . . . . . . . 17-20Executing a Parameterized SELECT That
Returns Multiple Rows . . . . . . . . . . . . . . . 17-21Executing
a Parameterized Singleton SELECT . . . . . . . . . . . . . . . . .
. . . . . 17-25
Handling a Parameterized User-Defined Routine . . . . . . . . .
. . . . . . . . . . . . . 17-26Executing a Parameterized Function .
. . . . . . . . . . . . . . . . . . . . . . . . 17-26Executing a
Parameterized Procedure. . . . . . . . . . . . . . . . . . . . . .
. . . 17-26
Handling a Parameterized UPDATE or DELETE Statement . . . . . .
. . . . . . . . . . . . 17-27
Part 4. Accessing DB2
Chapter 18. Introducing the Informix ESQL/C DB2 Option . . . . .
. . . . . . . . 18-1Overview of DB2 Access in ESQL/C . . . . . . .
. . . . . . . . . . . . . . . . . . . 18-1Creating Applications
That Access DB2 . . . . . . . . . . . . . . . . . . . . . . . . .
18-2Informix-specific SQL Statements to Update . . . . . . . . . .
. . . . . . . . . . . . . . 18-2
DESCRIBE statements With No INPUT Clause . . . . . . . . . . . .
. . . . . . . . . . 18-3SET ISOLATION Statement With RETAIN UPDATE
LOCKS . . . . . . . . . . . . . . . . . 18-3UPDATE table SET *
Statement . . . . . . . . . . . . . . . . . . . . . . . . . . .
18-3EXECUTE IMMEDIATE and PREPARE Statements . . . . . . . . . . .
. . . . . . . . . 18-3CREATE DATABASE Statement . . . . . . . . . .
. . . . . . . . . . . . . . . . . 18-3col[start, end] Syntax . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3GROUP BY
Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 18-3ORDER BY Clause . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 18-3
Contents ix
-
Statements Using CHAR_LENGTH, TO_DATE, TO_CHAR, TRIM Functions .
. . . . . . . . . . . 18-4Constraints Defined Within Parentheses .
. . . . . . . . . . . . . . . . . . . . . . . 18-4System Catalog
Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18-4Extended Types . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 18-4Optimizer Directives. . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 18-4
Using DB2-Specific SQL Syntax . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 18-4The sqlhosts File . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 18-4The esql Command . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18-5Setting the DB2CLI Environment Variable . . . . . . . . . . . .
. . . . . . . . . . . . 18-5Tracing . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 18-5Limitations in This
Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18-5
Chapter 19. Running Informix ESQL/C Applications with DB2
Databases . . . . . . 19-1In This Chapter . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 19-1Environment Variables .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19-1Data Type Mapping . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 19-2Error Message Mapping . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 19-5Application Behavior . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
19-5Transaction Management and Locking . . . . . . . . . . . . . .
. . . . . . . . . . . . 19-6Internationalization . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 19-6Writing or
Modifying Applications for DB2 . . . . . . . . . . . . . . . . . .
. . . . . . 19-7
Informix and DB2 Database Structures. . . . . . . . . . . . . .
. . . . . . . . . . . 19-7Database Object Names. . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 19-9DB2 Pages and Data
Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19-10SQL Built-In Functions . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 19-10Synonyms . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 19-12Primary Keys and Null Values .
. . . . . . . . . . . . . . . . . . . . . . . . . .
19-13Partitioning (Fragmenting) . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 19-13Use of the Rowid Column . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 19-13Referential Integrity
and Triggers . . . . . . . . . . . . . . . . . . . . . . . . . .
19-13Altering Tables . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 19-13Creating Temporary Tables . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 19-13Stored Procedures . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
19-13Character Strings . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 19-14Comments. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 19-14Concatenation and Casting of
Data . . . . . . . . . . . . . . . . . . . . . . . . . 19-14GROUP
BY Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 19-14ORDER BY Clause . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 19-14
Automatic Conversion of Informix-Specific SQL Syntax. . . . . .
. . . . . . . . . . . . . . 19-14Sample Program. . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 19-16
Part 5. Appendixes
Appendix A. The ESQL/C Example Programs. . . . . . . . . . . . .
. . . . . . A-1
Appendix B. ESQL/C Function Library . . . . . . . . . . . . . .
. . . . . . . . B-1IBM Informix ESQL/C Library Functions . . . . .
. . . . . . . . . . . . . . . . . . . . B-1bigintcvasc() . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-6bigintcvdbl() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-7bigintcvdec() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-8bigintcvflt() . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-9bigintcvifx_int8() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-10bigintcvint2() . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-11bigintcvint4() . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-12biginttoasc() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-13biginttodbl() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-14biginttodec() . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
B-15biginttoflt() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-16biginttoifx_int8() . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-17biginttoint2() . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-18
x IBM Informix ESQL/C Programmer’s Manual
-
biginttoint4() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-19bycmpr() . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . B-20bycopy() . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . B-22byfill() . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-24byleng() . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . B-26decadd(). . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . B-27deccmp() . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . B-29deccopy() . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-31deccvasc() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-33deccvdbl() . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-35deccvflt() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
B-37deccvint() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-39deccvlong() . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . B-41decdiv() . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . B-43dececvt()
and decfcvt() . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . B-45decmul() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . B-50decround() . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . B-52decsub() . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-54dectoasc() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-56dectodbl() . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-58dectoint() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
B-60dectolong() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . B-62dectrunc() . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . B-64dtaddinv() . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . B-66dtcurrent()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. B-68dtcvasc() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-70dtcvfmtasc() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-72dtextend() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . B-75dtsub() .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. B-77dtsubinv() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-79dttoasc() . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . B-81dttofmtasc() . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-83GetConnect() (Windows) . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-86ifx_cl_card() . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . B-88ifx_dececvt() and
ifx_decfcvt() . . . . . . . . . . . . . . . . . . . . . . . . . . .
. B-90ifx_defmtdate() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-91ifx_dtcvasc() . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . B-93ifx_dtcvfmtasc() . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-95ifx_dttofmtasc() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-97ifx_getenv(). . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . B-99ifx_getcur_conn_name() .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-100ifx_getserial8() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-101ifx_int8add() . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-102ifx_int8cmp() . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-104ifx_int8copy() . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-106ifx_int8cvasc() . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . B-108ifx_int8cvdbl() . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-111ifx_int8cvdec() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-113ifx_int8cvflt() . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . B-115ifx_int8cvint() . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-117ifx_int8cvlong() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-119ifx_int8div() . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-121ifx_int8mul() . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-123ifx_int8sub() . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-125ifx_int8toasc() . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-127ifx_int8todbl() . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-130ifx_int8todec() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-133ifx_int8toflt() . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . B-136ifx_int8toint(). . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-139ifx_int8tolong() . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-142ifx_lo_alter() . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-145
Contents xi
-
ifx_lo_close() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-146ifx_lo_col_info() . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-147ifx_lo_copy_to_file()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-148ifx_lo_copy_to_lo() . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-150ifx_lo_create() . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
B-151ifx_lo_def_create_spec() . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-153ifx_lo_filename() . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . B-154ifx_lo_from_buffer()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-155ifx_lo_lock() . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-156ifx_lo_open() . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-158ifx_lo_read() . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-160ifx_lo_readwithseek() . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-161ifx_lo_release() . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . B-163ifx_lo_seek() . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-164ifx_lo_spec_free() . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-166ifx_lo_specget_def_open_flags() . . . . .
. . . . . . . . . . . . . . . . . . . . . .
B-167ifx_lo_specget_estbytes() . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . B-168ifx_lo_specget_extsz() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
B-169ifx_lo_specget_flags() . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-170ifx_lo_specget_maxbytes() . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
B-171ifx_lo_specget_sbspace() . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-172ifx_lo_specset_def_open_flags(). . . . .
. . . . . . . . . . . . . . . . . . . . . . .
B-173ifx_lo_specset_estbytes() . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . B-174ifx_lo_specset_extsz() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
B-175ifx_lo_specset_flags() . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-176ifx_lo_specset_maxbytes() . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
B-177ifx_lo_specset_sbspace() . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-178ifx_lo_stat() . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . B-179ifx_lo_stat_atime()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-180ifx_lo_stat_cspec() . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-181ifx_lo_stat_ctime() . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
B-182ifx_lo_stat_free(). . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-183ifx_lo_stat_mtime_sec() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
B-184ifx_lo_stat_refcnt() . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-185ifx_lo_stat_size(). . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . B-186ifx_lo_tell() . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-187ifx_lo_to_buffer() . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-188ifx_lo_truncate() . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . B-189ifx_lo_unlock() . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-190ifx_lo_write() . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-191ifx_lo_writewithseek() . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . B-192ifx_lvar_alloc() . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-194ifx_putenv() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-195ifx_strdate() . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . B-196ifx_var_alloc() . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-198ifx_var_dealloc(). . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-199ifx_var_flag() . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-200ifx_var_freevar(). . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-201ifx_var_getdata() . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-202ifx_var_getlen() . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-203ifx_var_isnull() . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-204ifx_var_setdata(). . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-205ifx_var_setlen() . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-206ifx_var_setnull() . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-207incvasc() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-208incvfmtasc() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-210intoasc() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
B-213intofmtasc() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-215invdivdbl() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-218invdivinv() . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
B-220invextend() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-222
xii IBM Informix ESQL/C Programmer’s Manual
-
invmuldbl() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . B-224ldchar() . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . B-226rdatestr() . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . B-227rdayofweek()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-229rdefmtdate() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-231rdownshift() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-234ReleaseConnect() (Windows)
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-235rfmtdate() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-237rfmtdec() . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-240rfmtdouble() . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
B-243rfmtlong() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . B-246rgetlmsg() . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . B-249rgetmsg() . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . B-251risnull() .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-253rjulmdy() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-256rleapyear() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-258rmdyjul() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
B-260rsetnull() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-262rstod() . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-265rstoi() . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . B-267rstol()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . B-269rstrdate() . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-271rtoday() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . B-273rtypalign(). . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-274rtypmsize() . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-277rtypname() . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . B-280rtypwidth() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . B-282rupshift()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. B-285SetConnect() (Windows) . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . B-286sqgetdbs() . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . B-288sqlbreak() . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-291sqlbreakcallback() . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . B-293sqldetach() . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . B-295sqldone() . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
B-301sqlexit() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-302SqlFreeMem() . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . B-303sqlsignal() . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
B-304sqlstart() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-306stcat() . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-307stchar() . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . B-309stcmpr()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. B-310stcopy() . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . B-311stleng() . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . B-312
Appendix C. Examples for Smart-Large-Object Functions (IDS) . .
. . . . . . . . . C-1Prerequisites . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . C-1The create_clob.ec Program.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2
Storage Characteristics for the Example . . . . . . . . . . . .
. . . . . . . . . . . . C-2The get_lo_info.ec Program. . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . C-5The
upd_lo_descr.ec Program . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . C-8
Appendix D. Accessibility . . . . . . . . . . . . . . . . . . .
. . . . . . . . D-1Accessibility features for IBM Informix Dynamic
Server . . . . . . . . . . . . . . . . . . . . D-1
Accessibility Features . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . D-1Keyboard Navigation . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . D-1Related Accessibility
Information. . . . . . . . . . . . . . . . . . . . . . . . . . .
D-1IBM and Accessibility . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . D-1
Dotted Decimal Syntax Diagrams . . . . . . . . . . . . . . . . .
. . . . . . . . . . D-1
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . E-1
Contents xiii
-
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . E-3
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . X-1
xiv IBM Informix ESQL/C Programmer’s Manual
-
Introduction
In this Introduction. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . xvAbout This Publication . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . xv
Types of Users . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . xvSoftware Dependencies . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . xviAssumptions About Your Locale .
. . . . . . . . . . . . . . . . . . . . . . . . . .
xviDemonstration Databases . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . xvi
What’s New in ESQL/C for Client SDK . . . . . . . . . . . . . .
. . . . . . . . . . . xviiDocumentation Conventions . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . xvii
Technical Changes . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . xviiFeature, Product, and Platform Markup . . . . .
. . . . . . . . . . . . . . . . . . . xviiExample Code Conventions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Additional Documentation . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . xviiiCompliance with Industry Standards . . . . .
. . . . . . . . . . . . . . . . . . . . . xixSyntax Diagrams . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
How to Read a Command-Line Syntax Diagram . . . . . . . . . . .
. . . . . . . . . . . xxKeywords and Punctuation . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . xxiIdentifiers and Names .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
How to Provide Documentation Feedback. . . . . . . . . . . . . .
. . . . . . . . . . . xxii
In this IntroductionThis introduction provides an overview of
the information in this publication anddescribes the conventions it
uses.
About This PublicationThis publication explains how to use IBM®
Informix® ESQL/C, the Informiximplementation of embedded Structured
Query Language (SQL) for C (ESQL/C),to create client applications
with database-management capabilities. Thispublication is a
complete guide to the features of Informix ESQL/C that enableyou to
interact with the database server, access databases, manipulate the
data inyour program, and check for errors. However, certain
operating systems do notsupport every documented ESQL/C feature.
Check the Informix Client SoftwareDevelopment Kit (Client SDK)
Machine Notes® for your operating system todetermine exactly which
features do not operate in your environment.
This publication progresses from general topics to more advanced
programmingtechniques and examples.
Types of UsersThis publication is written primarily for C
programmers who want to embed SQLstatements in their programs to
access IBM Informix databases.
This publication assumes that you have the following
background:v A working knowledge of your computer, your operating
system, and the utilities
that your operating system providesv Some experience working
with relational or object-relational databases, or
exposure to relational database conceptsv C language
programming
The following users might also be interested in some of the
topics in this book:
© Copyright IBM Corp. 1996, 2009 xv
-
v Database server administratorsv Performance engineers
If you have limited experience with relational databases, SQL,
or your operatingsystem, refer to the IBM Informix Dynamic Server
Getting Started Guide for yourdatabase server for a list of
supplementary titles.
Software DependenciesIn places where this publication presents
database server-specific information, thisinformation applies to
one of the following database servers:v IBM Informix Dynamic Server
(IDS) Version 11.50v IBM Informix Extended Parallel Server (XPS)v
IBM Informix SEv IBM DB2 Universal Database™, Version 8.2 or
later
If you are using a database server that is not listed here, see
your release notes forinformation about client behavior on your
database server.
Note: All versions of IBM Informix ESQL/C support IPv6. For more
informationabout using IPv6 see the IBM Informix Administrator’s
Guide.
Assumptions About Your LocaleIBM Informix products can support
many languages, cultures, and code sets. Allculture-specific
information is brought together in a single environment, called
aGLS (Global Language Support) locale.
The examples in this publication are written with the assumption
that you areusing the default locale, en_us.8859-1. This locale
supports U.S. English formatconventions for dates, times, and
currency. In addition, this locale supports the ISO8859-1 code set,
which includes the ASCII code set plus many 8-bit characters suchas
é, è, and ñ.
If you plan to use nondefault characters in your data or your
SQL identifiers, or ifyou want to conform to the nondefault
collation rules of character data, you needto specify the
appropriate nondefault locale.
For instructions on how to specify a nondefault locale,
additional syntax, and otherconsiderations related to GLS locales,
see the IBM Informix GLS User’s Guide.
Demonstration DatabasesThe DB–Access utility, which is provided
with your IBM Informix database serverproducts, includes one or
more demonstration databases that contain informationabout a
fictitious wholesale sporting-goods distributor. You can create
andpopulate these demonstration databases with command files that
are included withthe database server.
Many examples in IBM Informix publications are based on these
databases. For acomplete explanation of how to create and populate
the demonstration databases,refer to your IBM Informix DB–Access
User’s Guide. For a description of thedemonstration databases and
their contents, see your IBM Informix Guide to SQL:Reference.
xvi IBM Informix ESQL/C Programmer’s Manual
++
-
The scripts that you use to install the demonstration databases
reside in the$INFORMIXDIR/bin directory on UNIX® and in the
%INFORMIXDIR%\bindirectory on Windows.
For additional information about IBM Informix ESQL/C and the
demonstrationdatabase, see Appendix A, “The ESQL/C Example
Programs,” on page A-1.
What’s New in ESQL/C for Client SDKThis publication includes
information about new features and changes in
existingfunctionality. The following changes and enhancements are
relevant to thispublication.
Table 1. What’s New in IBM Informix ESQL/C Programmer’s Manual
for Version 3.50.xC4
Overview Reference
Error Checking During Data Transfer
With the IFX_LOB_XFERSIZE environmentvariable, you can specify
the number ofkilobytes in a CLOB or BLOB to transferfrom a client
application to the databaseserver before checking whether an error
hasoccurred.
“Error Checking During Data Transfer” onpage 12-27
Table 2. What’s New in IBM Informix ESQL/C Programmer’s Manual
for Version 3.50.xC1
Overview Reference
This release introduces two data types,BIGINT and BIGSERIAL.
These data typeshave the same ranges as the existing INT8and
SERIAL8 data types, and have storageand computational
advantages.
“SQL Data Type Constants” on page 3-4
“Choosing Data Types for Host Variables” onpage 3-1
“Data Type Mapping” on page 19-2
Documentation ConventionsSpecial conventions are used in the
product documentation for IBM InformixDynamic Server.
Technical ChangesTechnical changes to the text are indicated by
special characters depending on theformat of the documentation.
HTML documentationNew or changed information is surrounded by
blue >> and
-
Some examples of this markup follow:
Dynamic Server
Identifies information that is specific to IBM Informix Dynamic
Server
End of Dynamic Server
Windows Only
Identifies information that is specific to the Windows®
operating system
End of Windows Only
This markup can apply to one or more paragraphs within a
section. When anentire section applies to a particular product or
platform, this is noted as part ofthe heading text, for
example:
Table Sorting (Windows)
Example Code ConventionsExamples of SQL code occur throughout
this publication. Except as noted, the codeis not specific to any
single IBM Informix application development tool.
If only SQL statements are listed in the example, they are not
delimited bysemicolons. For instance, you might see the code in the
following example:CONNECT TO stores_demo...
DELETE FROM customerWHERE customer_num = 121
...
COMMIT WORKDISCONNECT CURRENT
To use this SQL code for a specific product, you must apply the
syntax rules forthat product. For example, if you are using an SQL
API, you must use EXEC SQLat the start of each statement and a
semicolon (or other appropriate delimiter) atthe end of the
statement. If you are using DB–Access, you must delimit
multiplestatements with semicolons.
Tip: Ellipsis points in a code example indicate that more code
would be added ina full application, but it is not necessary to
show it to describe the conceptbeing discussed.
For detailed directions on using SQL statements for a particular
applicationdevelopment tool or SQL API, see the documentation for
your product.
Additional DocumentationDocumentation about IBM Informix
products is available in various formats.
You can view, search, and print all of the product documentation
from the IBMInformix Dynamic Server information center on the Web
at
http://publib.boulder.ibm.com/infocenter/idshelp/v115/index.jsp.
xviii IBM Informix ESQL/C Programmer’s Manual
http://publib.boulder.ibm.com/infocenter/idshelp/v115/index.jsphttp://publib.boulder.ibm.com/infocenter/idshelp/v115/index.jsp
-
For additional documentation about IBM Informix Dynamic Server
and relatedproducts, including release notes, machine notes, and
documentation notes, go tothe online product library page at
http://www.ibm.com/software/data/informix/techdocs.html.
Alternatively, you can access or install the product
documentationfrom the Quick Start CD that is shipped with the
product.
Compliance with Industry StandardsIBM Informix products are
compliant with various standards.
The American National Standards Institute (ANSI) and the
InternationalOrganization of Standardization (ISO) have jointly
established a set of industrystandards for the Structured Query
Language (SQL). IBM Informix SQL-basedproducts are fully compliant
with SQL-92 Entry Level (published as ANSIX3.135-1992), which is
identical to ISO 9075:1992. In addition, many features ofIBM
Informix database servers comply with the SQL-92 Intermediate and
FullLevel and X/Open SQL Common Applications Environment (CAE)
standards.
Syntax DiagramsSyntax diagrams use special components to
describe the syntax for statements andcommands.
Table 3. Syntax Diagram Components
Component represented in PDF Component represented in HTML
Meaning
>>---------------------- Statement begins.
-----------------------> Statement continues on nextline.
>----------------------- Statement continues fromprevious
line.
----------------------->< Statement ends.
--------SELECT---------- Required item.
--+-----------------+---'------LOCAL------'
Optional item.
---+-----ALL-------+---+--DISTINCT-----+'---UNIQUE------'
Required item with choice.One and only one item mustbe
present.
---+------------------+---+--FOR UPDATE-----+'--FOR READ
ONLY--'
Optional items with choiceare shown below the mainline, one of
which you mightspecify.
.---NEXT---------.----+----------------+---
+---PRIOR--------+'---PREVIOUS-----'
The values below the mainline are optional, one ofwhich you
might specify. Ifyou do not specify an item,the value above the
line willbe used as the default.
Introduction xix
http://www.ibm.com/software/data/informix/techdocs.htmlhttp://www.ibm.com/software/data/informix/techdocs.html
-
Table 3. Syntax Diagram Components (continued)
Component represented in PDF Component represented in HTML
Meaning
.-------,-----------.V |---+-----------------+---
+---index_name---+'---table_name---'
Optional items. Several itemsare allowed; a comma mustprecede
each repetition.
>>-| Table Reference |->< Reference to a
syntaxsegment.
Table Reference
|--+-----view--------+--|+------table------+'----synonym------'
Syntax segment.
How to Read a Command-Line Syntax DiagramCommand-line syntax
diagrams use similar elements to those of other syntaxdiagrams.
Some of the elements are listed in the table in Syntax
Diagrams.
Creating a No-Conversion Job
�� onpladm create job job-p project
-n -d device -D database �
� -t table �
� �(1)
Setting the Run Mode-S server -T target
��
Notes:
1 See page Z-1
This diagram has a segment named “Setting the Run Mode,” which
according tothe diagram footnote is on page Z-1. If this was an
actual cross-reference, youwould find this segment in on the first
page of Appendix Z. Instead, this segmentis shown in the following
segment diagram. Notice that the diagram uses segmentstart and end
components.
Setting the Run Mode:
xx IBM Informix ESQL/C Programmer’s Manual
|||||
-
-fdpa
lc
u n N
To see how to construct a command correctly, start at the top
left of the maindiagram. Follow the diagram to the right, including
the elements that you want.The elements in this diagram are case
sensitive because they illustrate utilitysyntax. Other types of
syntax, such as SQL, are not case sensitive.
The Creating a No-Conversion Job diagram illustrates the
following steps:1. Type onpladm create job and then the name of the
job.2. Optionally, type -p and then the name of the project.3. Type
the following required elements:v -nv -d and the name of the
devicev -D and the name of the databasev -t and the name of the
table
4. Optionally, you can choose one or more of the following
elements and repeatthem an arbitrary number of times:v -S and the
server namev -T and the target server namev The run mode. To set
the run mode, follow the Setting the Run Mode
segment diagram to type -f, optionally type d, p, or a, and then
optionallytype l or u.
5. Follow the diagram to the terminator.
Keywords and PunctuationKeywords are words reserved for
statements and all commands exceptsystem-level commands.
When a keyword appears in a syntax diagram, it is shown in
uppercase letters.When you use a keyword in a command, you can
write it in uppercase orlowercase letters, but you must spell the
keyword exactly as it appears in thesyntax diagram.
You must also use any punctuation in your statements and
commands exactly asshown in the syntax diagrams.
Identifiers and NamesVariables serve as placeholders for
identifiers and names in the syntax diagramsand examples.
You can replace a variable with an arbitrary name, identifier,
or literal, dependingon the context. Variables are also used to
represent complex syntax elements thatare expanded in additional
syntax diagrams. When a variable appears in a syntaxdiagram, an
example, or text, it is shown in lowercase italic.
Introduction xxi
-
The following syntax diagram uses variables to illustrate the
general form of asimple SELECT statement.
�� SELECT column_name FROM table_name ��
When you write a SELECT statement of this form, you replace the
variablescolumn_name and table_name with the name of a specific
column and table.
How to Provide Documentation FeedbackYou are encouraged to send
your comments about IBM Informix userdocumentation.
Use one of the following methods:v Send e-mail to
[email protected] Go to the information center at
http://publib.boulder.ibm.com/infocenter/
idshelp/v115/index.jsp and open the topic that you want to
comment on. Clickthe feedback link at the bottom of the page, fill
out the form, and submit yourfeedback.
v Add comments to topics directly in the IDS information center
and readcomments that were added by other users. Share information
about the productdocumentation, participate in discussions with
other users, rate topics, andmore! Find out more at
http://publib.boulder.ibm.com/infocenter/idshelp/v115/index.jsp?topic=/com.ibm.start.doc/contributing.htm.
Feedback from all methods is monitored by those who maintain the
userdocumentation. The feedback methods are reserved for reporting
errors andomissions in our documentation. For immediate help with a
technical problem,contact IBM Technical Support. For instructions,
see the IBM Informix TechnicalSupport Web site at
http://www.ibm.com/planetwide/.
We appreciate your suggestions.
xxii IBM Informix ESQL/C Programmer’s Manual
mailto:[email protected]://publib.boulder.ibm.com/infocenter/idshelp/v115/index.jsphttp://publib.boulder.ibm.com/infocenter/idshelp/v115/index.jsphttp://publib.boulder.ibm.com/infocenter/idshelp/v115/index.jsp?topic=/com.ibm.start.doc/contributing.htmhttp://publib.boulder.ibm.com/infocenter/idshelp/v115/index.jsp?topic=/com.ibm.start.doc/contributing.htmhttp://www.ibm.com/planetwide/
-
Part 1. What Is IBM Informix ESQL/C?
© Copyright IBM Corp. 1996, 2009
-
IBM Informix ESQL/C Programmer’s Manual
-
Chapter 1. Programming with IBM Informix ESQL/C
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 1-2What Is IBM Informix ESQL/C? . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1-2
ESQL/C Components. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 1-2ESQL/C Files for Windows . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 1-3ESQL/C Library Functions . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 1-3
Creating an ESQL/C Program . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 1-4Embedding SQL Statements. . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 1-4
Handling Case Sensitivity in Embedded SQL Statements . . . . . .
. . . . . . . . . . . . . 1-5Using Quotes and Escape Characters . .
. . . . . . . . . . . . . . . . . . . . . . . 1-6
Including Newline in Quoted Strings . . . . . . . . . . . . . .
. . . . . . . . . . 1-8Adding Comments . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 1-8Specifying Host Variables . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Declaring and Using Host Variables . . . . . . . . . . . . . . .
. . . . . . . . . . . . 1-9Declaring a Host Variable . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 1-10
Host-Variable Names . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 1-10Host-Variable Data Types . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 1-11Initial Host-Variable Values .
. . . . . . . . . . . . . . . . . . . . . . . . . . 1-11Scope of
Host Variables . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 1-11Sample Host-Variable Declarations . . . . . . . . . . . .
. . . . . . . . . . . . . 1-12
Assigning a Value to a Host Variable . . . . . . . . . . . . . .
. . . . . . . . . . . 1-13SQL Identifiers . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 1-13Null Values in Host
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . .
1-16
Using Host Variables in Data Structures . . . . . . . . . . . .
. . . . . . . . . . . . 1-16Arrays of Host Variables . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 1-17C Structures as Host
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17C
typedef Statements as Host Variables . . . . . . . . . . . . . . .
. . . . . . . . 1-18Pointers as Host Variables . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 1-18Function Parameters as Host
Variables. . . . . . . . . . . . . . . . . . . . . . . . 1-19
Using Host Variables in Windows Environments (Windows) . . . . .
. . . . . . . . . . . . 1-20Declaring Variables with Non-ANSI
Storage-Class Modifiers . . . . . . . . . . . . . . . . 1-20
Using Indicator Variables . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 1-22Declaring Indicator Variables . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1-22Associating an
Indicator Variable with a Host Variable . . . . . . . . . . . . . .
. . . . 1-23Indicating Null Values . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 1-23Indicating Truncated Values . . . . .
. . . . . . . . . . . . . . . . . . . . . . 1-24An Example Using
Indicator Variables . . . . . . . . . . . . . . . . . . . . . . . .
1-24
Using ESQL/C Header Files . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 1-25Declaring Function Prototypes . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1-27Including Header Files
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-28
Using ESQL/C Preprocessor Directives . . . . . . . . . . . . . .
. . . . . . . . . . . 1-28The include Directive . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1-29The define and undef
Directives . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-30The ifdef, ifndef, elif, else, and endif Directives . . . . . .
. . . . . . . . . . . . . . . . 1-31
Setting and Retrieving Environment Variables in Windows
Environments (Windows) . . . . . . . . . . 1-32InetLogin Structure
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-33
Fields of the InetLogin Structure . . . . . . . . . . . . . . .
. . . . . . . . . . . 1-34InetLogin Field Values . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1-37Precedence of
Configuration Values. . . . . . . . . . . . . . . . . . . . . . . .
. 1-38
Using Global ESQL/C Variables in a Windows Environment . . . . .
. . . . . . . . . . . . . 1-39A Sample IBM Informix ESQL/C Program
. . . . . . . . . . . . . . . . . . . . . . . . 1-39
Compiling the demo1 Program . . . . . . . . . . . . . . . . . .
. . . . . . . . . 1-39Guide to demo1.ec File . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 1-40
Line 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 1-40Lines 2 to 3 . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 1-40Lines 4 to 9 . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 1-40
© Copyright IBM Corp. 1996, 2009 1-1
-
Lines 10 to 12 . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 1-41Lines 13 to 17 . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 1-41Line 18 . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 1-41Lines 19 to 25 . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-41Lines
26 to 27 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 1-42Lines 28 to 29 . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 1-42Lines 30 to 32 . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 1-42
In This ChapterThis chapter discusses the following topics:v
What is IBM Informix ESQL/C?v Declaring and using host variables in
SQL statementsv Embedding SQL statements in C programsv Using
Informix ESQL/C preprocessor directivesv Using Informix ESQL/C
header files
Windows Only
v Setting and retrieving Informix ESQL/C environment variables
in Windowsenvironments
End of Windows Only
The last section of this chapter, “A Sample IBM Informix ESQL/C
Program” onpage 1-39, presents the demo1 sample program, which is
annotated. The demo1program illustrates the basic concepts of
Informix ESQL/C programming that thischapter introduces.
What Is IBM Informix ESQL/C?Informix ESQL/C is an SQL
application programming interface (API) that enables youto embed
Structured Query Language (SQL) statements directly into a C
program.The Informix ESQL/C preprocessor, esql, converts each SQL
statement and all IBMInformix-specific code to C-language source
code and invokes the C compiler tocompile it.
ESQL/C ComponentsInformix ESQL/C consists of the following
software components:v The Informix ESQL/C libraries of C functions,
which provide access to the
database server.v The Informix ESQL/C header files, which
provide definitions for the data
structures, constants, and macros useful to the Informix ESQL/C
program.v The esql command, which processes the Informix ESQL/C
source code to create
a C source file that it passes to the C compiler.v The finderr
utility on the UNIX system and the Informix Error Messages
Windows-based utility that enable you to obtain information
about IBMInformix-specific error messages.
Global Language Support
v The IBM Informix GLS locale and code-set-conversion files,
which providelocale-specific information.
1-2 IBM Informix ESQL/C Programmer’s Manual
-
For more information on these files, see the IBM Informix GLS
User’s Guide.
End of Global Language Support
ESQL/C Files for WindowsFor Windows environments, the Informix
ESQL/C product contains the followingadditional executable files:v
The Setnet32 utility is a Windows-based utility that enables you to
set
configuration information.For more information, see the IBM
Informix Client Products Installation Guide.
v The ILOGIN utility is a demonstration program that displays a
dialog box withfields for the connection parameters, for testing a
connection to the databaseserver (uses the stores7 database).For
more information, see the IBM Informix Client Products Installation
Guide.
v The ESQLMF.EXE multibyte filter changes escape characters in
multibyte stringsinto hexadecimal literals.
These Informix ESQL/C executable files are located in the
%INFORMIXDIR%\bin, %INFORMIXDIR%\lib, and %INFORMIXDIR%\demo
directories. The%INFORMIXDIR% variable represents the value of the
INFORMIXDIRenvironment variable.
ESQL/C Library FunctionsThe Informix ESQL/C library contains a
set of C functions that you can use inyour application. The library
functions are described in Appendix B, “ESQL/CFunction Library,” on
page B-1. These functions fall into the following categories:v Data
type alignment library functions provide support for computer-
independent size and alignment information for different data
types and assistin working with null database values.
v Character and string library functions provide character-based
manipulationssuch as comparison and copying.
v DECIMAL library functions support access to DECIMAL values
through thedecimal structure.
v Formatting functions enable you to specify display formats for
different datatypes.
v DATE library functions support access to DATE values.v
DATETIME and INTERVAL library functions support access to values of
these
data types through the datetime and interval structures,
respectively.v Error message functions provide support for
obtaining and formatting
Informix-specific error-message text.v Database server control
functions enable your application to implement such
features as cancelling queries and terminating connections.v
INT8 library functions enable you to access INT8 values through the
int8
structure.
Dynamic Server
v Smart-large-object library functions provide a file-like
interface to the BLOB andCLOB data types.
End of Dynamic Server
Chapter 1. Programming with IBM Informix ESQL/C 1-3
-
Creating an ESQL/C ProgramYou create an Informix ESQL/C program
with the following steps:1. Embed Informix ESQL/C statements in a
c-language source program to
perform the following tasks:v Define host variables to store
data for transfer between the Informix ESQL/C
program and the database server.v Access the database server
through SQL statements.v Provide directives for the Informix ESQL/C
preprocessor and the C compiler.
2. Preprocess the Informix ESQL/C source file with the esql
command to create aC-language source file and invoke the C
compiler.
3. As necessary, correct errors reported by the preprocessor and
the compiler andrepeat step 2.
4. Using the esql command, link the compiled object code into
one or moreexecutable files.
An Informix ESQL/C source file can contain the following types
of statements:v Preprocessor directives
– Informix ESQL/C preprocessor directives to create simple macro
definitions,include Informix ESQL/C files, and perform conditional
Informix ESQL/Ccompilation.
– C preprocessor directives to create macro definitions, include
system and Csource files, and perform conditional C
compilation.
v Language statements– Informix ESQL/C host variable definitions
to store data for transfer between
the Informix ESQL/C program and the database server.– Embedded
SQL statements to communicate with the database server.– C language
statements to provide program logic.
For information on C preprocessor directives and C language
statements, refer to aC programming text. This chapter provides an
overview of embedded SQLstatements (page 1-4), Informix ESQL/C host
variables (page 1-9), InformixESQL/C preprocessor directives (page
1-28), and Informix ESQL/C header files(page 1-25).
Your Informix ESQL/C source code file name can have either of
the followingforms:v esqlc_source.ecv esqlc_source.ecp
The particular suffix that your Informix ESQL/C source file has
determines thedefault order in which that source file gets compiled
by the esql command. The .ecsuffix is the default suffix. For more
information on the .ecp suffix and thenon-default order of
compilation, see “Running the C Preprocessor Before theESQL/C
Preprocessor” on page 2-17.
Embedding SQL StatementsAn Informix ESQL/C program can use SQL
statements to communicate with thedatabase server. The program can
use both static and dynamic SQL statements. Astatic SQL statement
is one in which all the components are known when youcompile the
program. A dynamic SQL statement is one in which you do not
know
1-4 IBM Informix ESQL/C Programmer’s Manual
-
all the components at compile time; the program receives all or
part of thestatement at runtime. For a description of dynamic SQL,
see Chapter 14, “UsingDynamic SQL,” on page 14-1.
You can embed SQL statements in a C function with one of two
formats:v The EXEC SQL keywords:
EXEC SQL SQL_statement;
Using EXEC SQL keywords is the ANSI-compliant method to embed an
SQLstatement.
v The dollar sign ($) notation:$SQL_statement;
In either of these formats, replace SQL_statement with the
complete text of a validstatement. Informix ESQL/C statements can
include host variables in most placeswhere you can use a constant.
For any exceptions, see the syntax of individualstatements in the
IBM Informix Guide to SQL: Syntax.
This section describes the following topics that are related to
using embedded SQLstatements in an Informix ESQL/C program:v Case
sensitivity of identifiersv Using quotes and escape charactersv
Commenting statementsv Host variablesv Header files
Handling Case Sensitivity in Embedded SQL StatementsTable 1-1
describes how the Informix ESQL/C preprocessor treats upper case
andlower case letters.
Table 1-1. Case Sensitivity in ESQL/C Files
ESQL/C IdentifierCaseSensitive Example
Host variable Yes Informix ESQL/C treats the variables fname and
Fname as distinct variables:
EXEC SQL BEGIN DECLARE SECTION;char fna
