-
INFORMIX-ESQL/C
Programmer’s Manual
INFORMIX-OnLine Dynamic Server, Version 7.2xINFORMIX-OnLine
Workgroup Server, Version 7.2xINFORMIX-OnLine XPS, Version
8.1xINFORMIX-SE, Version 7.2x,INFORMIX-Universal Server, Version
9.1x
®
Version 9.13October 1997Part No. 000-4161
-
ii INFORMIX-ESQL/C P
Published by INFORMIX® Press Informix Software, Inc.4100
Bohannon DriveMenlo Park, CA 94025
Copyright 1981-1997 by Informix Software, Inc. or their
subsidiaries, provided that portions may becopyrighted by third
parties, as set forth in documentation. All rights reserved.
The following are worldwide trademarks of Informix Software,
Inc., or its subsidiaries, registered in theUnited States of
America as indicated by “®,” and in numerous other countries
worldwide:
INFORMIX; INFORMIX-OnLine Dynamic Server; DataBlade
The following are worldwide trademarks of the indicated owners
or their subsidiaries, registered in theUnited States of America as
indicated by “®,” and in numerous other countries worldwide:
Adobe Systems Incorporated: PostScript
Hewlett-Packard: Hewlett-Packard; HP
Microsoft Corporation: Microsoft; MS; MS-DOS; CodeView; MS
Windows; Windows; WindowsNT; ODBC; Visual Basic; Visual
C++Microsoft Memory Management Product: HIMEM.SYS(“DOS” as used
herein refers to MS-DOS and/or PC-DOS operating systems.)
Open Software Foundation, Inc.: Open Software Foundation; OSF;
OSF DCESun Microsystems, Inc.: SunX/OpenCompany Ltd.: UNIX;
X/Open
All other marks or symbols are registered trademarks or
trademarks of their respective owners.
Documentation Team: Bob Berry, Twila Booth, Evelyn
Eldridge-Diaz, John Francis, Smita Joshi
To the extent that this software allows the user to store,
display, and otherwise manipulate various forms ofdata, including,
without limitation, multimedia content such as photographs, movies,
music and other binarylarge objects (blobs), use of any single blob
may potentially infringe upon numerous different
third-partyintellectual and/or proprietary rights. It is the user's
responsibility to avoid infringements of any such third-party
rights.
RESTRICTED RIGHTS/SPECIAL LICENSE RIGHTS
Software and documentation acquired with US Government funds are
provided with rights as follows: (1) iffor civilian agency use,
with Restricted Rights as defined in FAR 52.227-19; (2) if for
Dept. of Defense use, withrights as restricted by vendor's standard
license, unless superseded by negotiated vendor license as
prescribedin DFAR 227.7202. Any whole or partial reproduction of
software or documentation marked with this legendmust reproduce the
legend.
rogrammer’s Manual
-
Table of Contents
Table ofContents
IntroductionAbout This Manual . . . . . . . . . . . . . . . . .
. 3
Types of Users . . . . . . . . . . . . . . . . . . 3Software
Dependencies . . . . . . . . . . . . . . . 4Assumptions About Your
Locale. . . . . . . . . . . . 4Demonstration Database . . . . . . .
. . . . . . . 5
Major Features . . . . . . . . . . . . . . . . . . .
5Documentation Conventions . . . . . . . . . . . . . . 6
Typographical Conventions . . . . . . . . . . . . . 7Icon
Conventions . . . . . . . . . . . . . . . . . 8Command-Line
Conventions . . . . . . . . . . . . . 10
Additional Documentation . . . . . . . . . . . . . . . 12On-Line
Manuals . . . . . . . . . . . . . . . . . 13Printed Manuals . . . .
. . . . . . . . . . . . . 13Error Message Files . . . . . . . . . .
. . . . . . 13Documentation Notes, Release Notes, Machine Notes . .
. . 14
Compliance with Industry Standards . . . . . . . . . . .
15Informix Welcomes Your Comments . . . . . . . . . . . . 15
Section I What Is INFORMIX-ESQL/C?
Chapter 1 Programming with INFORMIX-ESQL/CWhat Is
INFORMIX-ESQL/C? . . . . . . . . . . . . . . 1-5
ESQL/C Executable Files for Windows . . . . . . . . . 1-6ESQL/C
Library Functions . . . . . . . . . . . . . 1-7Creating an ESQL/C
Program . . . . . . . . . . . . 1-8
-
iv INFOR
Compiling an ESQL/C Program . . . . . . . . . . . 1-9Default
Compilation Order . . . . . . . . . . . . . 1-11Running the C
Preprocessor First . . . . . . . . . . . 1-12
Using ESQL/C Preprocessor Directives . . . . . . . . . . 1-12The
include Directive . . . . . . . . . . . . . . . 1-13The define and
undef Directives . . . . . . . . . . . 1-14The ifdef, ifndef, elif,
else, and endif Directives . . . . . . 1-16
Embedding SQL Statements . . . . . . . . . . . . . .
1-17Handling Case Sensitivity in Embedded SQL
Statements . . . . . . . . . . . . . . . . 1-18Using Quotes and
Escape Characters . . . . . . . . . . 1-19Adding Comments . . . . .
. . . . . . . . . . . 1-21Specifying Host Variables . . . . . . . .
. . . . . . 1-21Using ESQL/C Header Files . . . . . . . . . . . . .
1-22
Declaring and Using Host Variables in SQL Statements . . . . .
1-27Declaring a Host Variable . . . . . . . . . . . . . .
1-27Assigning a Value to a Host Variable . . . . . . . . . .
1-32Using Host Variables in Data Structures . . . . . . . . .
1-36Using Indicator Variables . . . . . . . . . . . . . . 1-42
Using the esql Command . . . . . . . . . . . . . . .
1-47Requirements for Using esql . . . . . . . . . . . . .
1-48Syntax of the esql Command. . . . . . . . . . . . . 1-48Options
That Affect Preprocessing . . . . . . . . . . . 1-58Running the C
Preprocessor Before the ESQL/C
Preprocessor . . . . . . . . . . . . . . . 1-66Preprocessor
Options Specific to Windows
Environments. . . . . . . . . . . . . . . 1-73Compiling and
Linking Options of the esql Command . . . . . 1-75
Syntax of the Compiling/Linking Options for UNIX . . . .
1-75Syntax of the Compiling/Linking Options for Windows
Environments. . . . . . . . . . . . . . . 1-77Special Compile
Options for Windows Environments . . . . 1-81General Options That
Affect Linking . . . . . . . . . . 1-86Special Linking Options for
Windows Environments . . . . 1-87Windows Operating System Processor
Options Available to
the esql Command . . . . . . . . . . . . . 1-90Accessing the
ESQL Client-Interface DLL in Windows
Environments. . . . . . . . . . . . . . . 1-94
MIX-ESQL/C Programmer’s Manual
-
Setting and Retrieving Environment Variables in
WindowsEnvironments . . . . . . . . . . . . . . . . 1-97
ifx_putenv() . . . . . . . . . . . . . . . . . . .
1-100ifx_getenv() . . . . . . . . . . . . . . . . . . .
1-102InetLogin Structure . . . . . . . . . . . . . . . . 1-103
Using Host Variables in Windows Environments . . . . . . .
1-112Declaring Variables with Non-ANSI Storage-Class
Modifiers . . . . . . . . . . . . . . . . . 1-112Using Global
ESQL/C Variables . . . . . . . . . . . . 1-115
A Sample INFORMIX-ESQL/C Program . . . . . . . . . .
1-116Compiling the demo1 Program . . . . . . . . . . . . 1-116Guide
to demo1.ec File . . . . . . . . . . . . . . . 1-116
Chapter 2 INFORMIX-ESQL/C Data TypesChoosing Data Types for Host
Variables . . . . . . . . . . . 2-3
Defined Constants for Data Types . . . . . . . . . . . 2-7Header
Files for Data Types . . . . . . . . . . . . . 2-11
The BOOLEAN Data Type . . . . . . . . . . . . . . . 2-13Data
Conversion . . . . . . . . . . . . . . . . . . . 2-15
Fetching and Inserting with Host Variables . . . . . . . .
2-15Arithmetic Operations . . . . . . . . . . . . . . . 2-19
Data-Type Alignment Library Functions . . . . . . . . . .
2-23risnull() . . . . . . . . . . . . . . . . . . . .
2-24rsetnull() . . . . . . . . . . . . . . . . . . . .
2-27rtypalign() . . . . . . . . . . . . . . . . . . .
2-30rtypmsize() . . . . . . . . . . . . . . . . . . .
2-33rtypname() . . . . . . . . . . . . . . . . . . .
2-36rtypwidth() . . . . . . . . . . . . . . . . . . . 2-39
Chapter 3 Working with Character and String Data TypesCharacter
Data Types . . . . . . . . . . . . . . . . . 3-3
The char Data Type . . . . . . . . . . . . . . . . 3-4The
fixchar Data Type . . . . . . . . . . . . . . . 3-5The string Data
Type . . . . . . . . . . . . . . . . 3-5The varchar Data Type . . .
. . . . . . . . . . . . 3-6The lvarchar Data Type . . . . . . . . .
. . . . . . 3-9
Fetching and Inserting Character Data Types . . . . . . . . .
3-11Fetching and Inserting CHAR Data . . . . . . . . . . .
3-11Fetching and Inserting VARCHAR Data . . . . . . . . .
3-12Fetching and Inserting lvarchar Data . . . . . . . . . .
3-17Fetching and Inserting with an ANSI-Compliant Database . . .
3-18
Table of Contents v
-
vi INFOR
Character and String Library Functions . . . . . . . . . .
3-19bycmpr() . . . . . . . . . . . . . . . . . . . 3-21bycopy() . .
. . . . . . . . . . . . . . . . . . 3-24byfill() . . . . . . . . .
. . . . . . . . . . . 3-26byleng() . . . . . . . . . . . . . . . .
. . . . 3-28ldchar() . . . . . . . . . . . . . . . . . . . .
3-30rdownshift() . . . . . . . . . . . . . . . . . . 3-32rstod() .
. . . . . . . . . . . . . . . . . . . 3-34rstoi() . . . . . . . . .
. . . . . . . . . . . . 3-36rstol() . . . . . . . . . . . . . . . .
. . . . . 3-38rupshift() . . . . . . . . . . . . . . . . . . .
3-40stcat() . . . . . . . . . . . . . . . . . . . . . 3-42stchar()
. . . . . . . . . . . . . . . . . . . . 3-44stcmpr() . . . . . . .
. . . . . . . . . . . . . 3-46stcopy() . . . . . . . . . . . . . .
. . . . . . 3-48stleng() . . . . . . . . . . . . . . . . . . . .
3-50
Chapter 4 Working with the DECIMAL Data TypeThe SQL DECIMAL Data
Type . . . . . . . . . . . . . 4-3
The decimal Data Type . . . . . . . . . . . . . . . 4-4Implicit
Data Conversion for decimal Values . . . . . . . 4-7Operations on
decimal Values . . . . . . . . . . . . 4-7Data Conversion for
decimal Values . . . . . . . . . . 4-7
The decimal Library Functions . . . . . . . . . . . . .
4-8decadd() . . . . . . . . . . . . . . . . . . . . 4-9deccmp() . .
. . . . . . . . . . . . . . . . . 4-11deccopy() . . . . . . . . . .
. . . . . . . . . 4-13deccvasc() . . . . . . . . . . . . . . . . .
. . 4-15deccvdbl() . . . . . . . . . . . . . . . . . . .
4-18deccvint() . . . . . . . . . . . . . . . . . . .
4-20deccvlong() . . . . . . . . . . . . . . . . . . . 4-22decdiv()
. . . . . . . . . . . . . . . . . . . . 4-24dececvt() and decfcvt()
. . . . . . . . . . . . . . . 4-26decmul() . . . . . . . . . . . .
. . . . . . . . 4-32decround() . . . . . . . . . . . . . . . . . .
. 4-34decsub() . . . . . . . . . . . . . . . . . . . .
4-37dectoasc() . . . . . . . . . . . . . . . . . . . 4-39dectodbl()
. . . . . . . . . . . . . . . . . . . 4-42dectoint() . . . . . . .
. . . . . . . . . . . . 4-44dectolong() . . . . . . . . . . . . . .
. . . . . 4-47dectrunc() . . . . . . . . . . . . . . . . . . .
4-49
MIX-ESQL/C Programmer’s Manual
-
Chapter 5 Working with Numeric Data TypesThe Integer Data Types
. . . . . . . . . . . . . . . . 5-4The Floating-Point Data Types .
. . . . . . . . . . . . . 5-5
Declaring float Host Variables . . . . . . . . . . . . .
5-5Implicit Data Conversion . . . . . . . . . . . . . . 5-6
The INT8 and SERIAL8 SQL Data Types . . . . . . . . . . 5-7The
int8 Data Type. . . . . . . . . . . . . . . . . 5-7Implicit Data
Conversion for int8 Values . . . . . . . . . 5-8Operations on int8
Values . . . . . . . . . . . . . . 5-8Data Conversion for int8
Values . . . . . . . . . . . . 5-8
The int8 Library Functions . . . . . . . . . . . . . . .
5-9ifx_getserial8() . . . . . . . . . . . . . . . . . .
5-10ifx_int8add() . . . . . . . . . . . . . . . . . . .
5-12ifx_int8cmp() . . . . . . . . . . . . . . . . . .
5-13ifx_int8copy() . . . . . . . . . . . . . . . . . .
5-14ifx_int8cvasc() . . . . . . . . . . . . . . . . . .
5-15ifx_int8cvdbl() . . . . . . . . . . . . . . . . . .
5-16ifx_int8cvdec() . . . . . . . . . . . . . . . . . .
5-17ifx_int8cvint() . . . . . . . . . . . . . . . . . .
5-18ifx_int8cvlong() . . . . . . . . . . . . . . . . . .
5-19ifx_int8div() . . . . . . . . . . . . . . . . . . .
5-20ifx_int8mul() . . . . . . . . . . . . . . . . . . .
5-21ifx_int8sub() . . . . . . . . . . . . . . . . . . .
5-22ifx_int8toasc() . . . . . . . . . . . . . . . . . .
5-23ifx_int8todbl() . . . . . . . . . . . . . . . . . .
5-24ifx_int8todec() . . . . . . . . . . . . . . . . . .
5-25ifx_int8toint() . . . . . . . . . . . . . . . . . .
5-26ifx_int8tolong() . . . . . . . . . . . . . . . . . . 5-27
Formatting Numeric Strings . . . . . . . . . . . . . . .
5-28Numeric-Formatting Functions . . . . . . . . . . . . . .
5-34
rfmtdec() . . . . . . . . . . . . . . . . . . . .
5-35rfmtdouble() . . . . . . . . . . . . . . . . . . .
5-38rfmtlong(). . . . . . . . . . . . . . . . . . . . 5-41
Chapter 6 Working with Time Data TypesThe SQL DATE Data Type . .
. . . . . . . . . . . . . 6-3
Formatting Date Strings . . . . . . . . . . . . . . . 6-4DATE
Library Functions . . . . . . . . . . . . . . . . 6-5
rdatestr() . . . . . . . . . . . . . . . . . . . . 6-6Return
Codes . . . . . . . . . . . . . . . . . . 6-6rdayofweek() . . . . .
. . . . . . . . . . . . . 6-8
Table of Contents vii
-
viii INFO
rdefmtdate() . . . . . . . . . . . . . . . . . . 6-10rfmtdate()
. . . . . . . . . . . . . . . . . . . 6-14rjulmdy() . . . . . . . .
. . . . . . . . . . . 6-17rleapyear() . . . . . . . . . . . . . . .
. . . . 6-19rmdyjul() . . . . . . . . . . . . . . . . . . .
6-21rstrdate() . . . . . . . . . . . . . . . . . . . 6-23rtoday() .
. . . . . . . . . . . . . . . . . . . 6-26
The SQL DATETIME and INTERVAL Data Types . . . . . . . 6-28The
datetime Data Type . . . . . . . . . . . . . . 6-29The interval
Data Type . . . . . . . . . . . . . . . 6-30Macros for datetime and
interval Data Types . . . . . . . 6-31Fetching and Inserting
DATETIME and INTERVAL Values . . 6-33ANSI SQL Standards for
DATETIME and INTERVAL
Values . . . . . . . . . . . . . . . . . 6-36Operations on
datetime and interval Values . . . . . . . 6-36Data Conversion for
datetime and interval Values . . . . . 6-37
DATETIME and INTERVAL Library Functions . . . . . . . .
6-38dtaddinv() . . . . . . . . . . . . . . . . . . .
6-40dtcurrent() . . . . . . . . . . . . . . . . . . . 6-42dtcvasc()
. . . . . . . . . . . . . . . . . . . . 6-44dtcvfmtasc() . . . . .
. . . . . . . . . . . . . 6-47dtextend() . . . . . . . . . . . . .
. . . . . . 6-51dtsub() . . . . . . . . . . . . . . . . . . . .
6-54dtsubinv() . . . . . . . . . . . . . . . . . . . 6-57dttoasc()
. . . . . . . . . . . . . . . . . . . . 6-59dttofmtasc() . . . . .
. . . . . . . . . . . . . 6-62incvasc() . . . . . . . . . . . . . .
. . . . . . 6-65incvfmtasc() . . . . . . . . . . . . . . . . . .
6-68intoasc() . . . . . . . . . . . . . . . . . . . .
6-71intofmtasc(). . . . . . . . . . . . . . . . . . .
6-74invdivdbl() . . . . . . . . . . . . . . . . . . .
6-77invdivinv() . . . . . . . . . . . . . . . . . . .
6-80invextend() . . . . . . . . . . . . . . . . . . .
6-82invmuldbl() . . . . . . . . . . . . . . . . . . 6-85
Chapter 7 Working with INFORMIX-Universal Server Smart Large
ObjectsData Structures for Smart Large Objects . . . . . . . . . .
7-6
Declaring a Host Variable . . . . . . . . . . . . . . 7-7The
LO-Specification Structure . . . . . . . . . . . . 7-7The
LO-Pointer Structure . . . . . . . . . . . . . . 7-16The LO File
Descriptor . . . . . . . . . . . . . . . 7-20
RMIX-ESQL/C Programmer’s Manual
-
Creating a Smart Large Object . . . . . . . . . . . . . .
7-21Accessing a Smart Large Object . . . . . . . . . . . . . .
7-22
Selecting a Smart Large Object . . . . . . . . . . . .
7-22Opening a Smart Large Object. . . . . . . . . . . . .
7-23Deletion of a Smart Large Object . . . . . . . . . . . .
7-28Modifying a Smart Large Object . . . . . . . . . . . .
7-28Closing a Smart Large Object . . . . . . . . . . . . . 7-29
Obtaining Status of a Smart Large Object . . . . . . . . . .
7-29Obtaining a Valid LO-Pointer Structure . . . . . . . . .
7-30Allocating and Accessing an LO-Status Structure . . . . . .
7-30Deallocating the LO-Status Structure . . . . . . . . . .
7-32
Reading and Writing Smart Large Objects on an Optical Disc . . .
7-32The ESQL/C API for Smart Large Objects . . . . . . . . . .
7-33
ifx_lo_alter() . . . . . . . . . . . . . . . . . . .
7-36ifx_lo_close(). . . . . . . . . . . . . . . . . . .
7-38ifx_lo_col_info() . . . . . . . . . . . . . . . . .
7-39ifx_lo_copy_to_file() . . . . . . . . . . . . . . . .
7-41ifx_lo_copy_to_lo() . . . . . . . . . . . . . . . .
7-44ifx_lo_create() . . . . . . . . . . . . . . . . . .
7-46ifx_lo_def_create_spec() . . . . . . . . . . . . . . .
7-49ifx_lo_filename() . . . . . . . . . . . . . . . . .
7-50ifx_lo_from_buffer() . . . . . . . . . . . . . . . .
7-52ifx_lo_open(). . . . . . . . . . . . . . . . . . .
7-53ifx_lo_read() . . . . . . . . . . . . . . . . . . .
7-55ifx_lo_readwithseek(). . . . . . . . . . . . . . . .
7-57ifx_lo_release() . . . . . . . . . . . . . . . . . .
7-59ifx_lo_seek() . . . . . . . . . . . . . . . . . . .
7-61ifx_lo_spec_free() . . . . . . . . . . . . . . . . .
7-63ifx_lo_specget_estbytes() . . . . . . . . . . . . . .
7-64ifx_lo_specget_extsz() . . . . . . . . . . . . . . .
7-66ifx_lo_specget_flags() . . . . . . . . . . . . . . . .
7-67ifx_lo_specget_maxbytes() . . . . . . . . . . . . . .
7-69ifx_lo_specget_sbspace(). . . . . . . . . . . . . . .
7-71ifx_lo_specset_estbytes(). . . . . . . . . . . . . . .
7-73ifx_lo_specset_extsz() . . . . . . . . . . . . . . . .
7-75ifx_lo_specset_flags() . . . . . . . . . . . . . . . .
7-77ifx_lo_specset_maxbytes() . . . . . . . . . . . . . .
7-79ifx_lo_specset_sbspace() . . . . . . . . . . . . . . .
7-80ifx_lo_stat() . . . . . . . . . . . . . . . . . . .
7-81ifx_lo_stat_atime() . . . . . . . . . . . . . . . . .
7-83ifx_lo_stat_cspec() . . . . . . . . . . . . . . . . .
7-84ifx_lo_stat_ctime() . . . . . . . . . . . . . . . . . 7-86
Table of Contents ix
-
x INFOR
ifx_lo_stat_free() . . . . . . . . . . . . . . . . .
7-87ifx_lo_stat_mtime_sec() . . . . . . . . . . . . . .
7-88ifx_lo_stat_refcnt() . . . . . . . . . . . . . . . .
7-89ifx_lo_stat_size() . . . . . . . . . . . . . . . . .
7-91ifx_lo_tell() . . . . . . . . . . . . . . . . . . .
7-92ifx_lo_to_buffer() . . . . . . . . . . . . . . . . .
7-93ifx_lo_truncate() . . . . . . . . . . . . . . . . .
7-95ifx_lo_write() . . . . . . . . . . . . . . . . . .
7-96ifx_lo_writewithseek() . . . . . . . . . . . . . . . 7-98
The create_clob Program . . . . . . . . . . . . . . .
7-100Storage Characteristics for the Example . . . . . . . . .
7-100Source for the create_clob.ec File . . . . . . . . . . .
7-101
Chapter 8 Working with Simple Large ObjectsChoosing a
Large-Object Data Type . . . . . . . . . . . . 8-4Programming with
Simple Large Objects . . . . . . . . . . 8-5
Declaring a Host Variable for a Simple Large Object. . . . .
8-5Accessing the Locator Structure. . . . . . . . . . . . 8-6
Locating Simple Large Objects in Memory . . . . . . . . .
8-11Allocating the Memory Buffer . . . . . . . . . . . .
8-12Selecting a Simple Large Object into Memory . . . . . . .
8-15Inserting a Simple Large Object from Memory. . . . . . .
8-17
Locating Simple Large Objects in Files . . . . . . . . . . .
8-19Locating Simple Large Objects in Open Files . . . . . . .
8-21Locating Simple Large Objects in Named Files . . . . . .
8-26
Using User-Defined Simple-Large-Object Locations . . . . . .
8-31Selecting a Simple Large Object into a User-Defined
Location . . . . . . . . . . . . . . . . 8-33Inserting a Simple
Large Object into a User-Defined
Location . . . . . . . . . . . . . . . . 8-34Creating the
User-Defined Simple-Large-Object Functions . . 8-35
Reading and Writing Simple Large Objects to an Optical Disc . .
. 8-40The dispcat_pic Program . . . . . . . . . . . . . . .
8-44
Loading the Simple-Large-Object Images . . . . . . . .
8-45Compiling the dispcat_pic Program . . . . . . . . . . 8-48Guide
to the dispcat_pic.ec File . . . . . . . . . . . . 8-50Guide to the
prdesc.c File . . . . . . . . . . . . . . 8-66Guide to the
inpfuncs.c File . . . . . . . . . . . . . 8-68
MIX-ESQL/C Programmer’s Manual
-
Chapter 9 Working with INFORMIX-Universal Server Complex Data
TypesAccessing a Collection . . . . . . . . . . . . . . . . .
9-4
Declaring Collection Variables. . . . . . . . . . . . .
9-5Managing Memory for Collections . . . . . . . . . . .
9-12Operating on a Collection Variable . . . . . . . . . . .
9-13Saving into a Collection Column . . . . . . . . . . . .
9-40Operating on a Collection Column . . . . . . . . . . .
9-41ifx_cl_card() . . . . . . . . . . . . . . . . . . .
9-45Accessing Row Types . . . . . . . . . . . . . . . .
9-48Declaring Row Variables . . . . . . . . . . . . . .
9-49Managing Memory for Rows . . . . . . . . . . . . .
9-57Operating on a Row Variable . . . . . . . . . . . . .
9-58Saving into a Row-Type Column . . . . . . . . . . . .
9-71Accessing a Typed Table . . . . . . . . . . . . . . .
9-72Operating on a Row-Type Column . . . . . . . . . . . 9-73
Chapter 10 Working with INFORMIX-Universal Server Opaque Data
TypesThe SQL Opaque Data Type . . . . . . . . . . . . . . .
10-3Accessing the External Format of an Opaque Type . . . . . . .
10-6
Declaring lvarchar Host Variables . . . . . . . . . . .
10-7Using lvarchar Host Variables . . . . . . . . . . . . .
10-11
Accessing the Internal Format of an Opaque Type . . . . . . .
10-17Accessing a Fixed-Length Opaque Type . . . . . . . . .
10-18Accessing a Varying-Length Opaque Type . . . . . . . .
10-23
The lvarchar pointer and var binary Library Functions . . . . .
10-32ifx_var_alloc() . . . . . . . . . . . . . . . . . .
10-33ifx_var_dealloc() . . . . . . . . . . . . . . . . .
10-35ifx_var_flag() . . . . . . . . . . . . . . . . . .
10-37ifx_var_getdata() . . . . . . . . . . . . . . . . .
10-39ifx_var_getlen() . . . . . . . . . . . . . . . . . .
10-40ifx_var_isnull() . . . . . . . . . . . . . . . . . .
10-41ifx_var_setdata() . . . . . . . . . . . . . . . . .
10-42ifx_var_setlen() . . . . . . . . . . . . . . . . . .
10-44ifx_var_setnull() . . . . . . . . . . . . . . . . . 10-46
Accessing Predefined Opaque Data Types . . . . . . . . . .
10-48
Table of Contents xi
-
xii INFO
Section II Database Server Communication
Chapter 11 Exception HandlingObtaining Diagnostic Information
After an SQL Statement . . . . 11-4
Types of Diagnostic Information . . . . . . . . . . . 11-4Types
of Status Variables . . . . . . . . . . . . . . 11-6
Exception Handling with SQLSTATE . . . . . . . . . . . 11-6Using
GET DIAGNOSTICS . . . . . . . . . . . . . 11-7Using the SQLSTATE
Variable . . . . . . . . . . . . 11-12Checking for Exceptions with
SQLSTATE . . . . . . . . 11-19
Exception Handling with the sqlca Structure . . . . . . . .
11-27Fields of the sqlca Structure . . . . . . . . . . . . .
11-28Using the SQLCODE Variable . . . . . . . . . . . .
11-32Checking for Exceptions with sqlca . . . . . . . . . .
11-34Displaying Error Text . . . . . . . . . . . . . . . 11-40
Choosing an Exception-Handling Strategy . . . . . . . . .
11-41Checking After Each SQL Statement . . . . . . . . . . 11-41The
WHENEVER Statement . . . . . . . . . . . . . 11-45
Library Functions for Retrieving Error Messages . . . . . . .
11-47rgetlmsg() . . . . . . . . . . . . . . . . . . .
11-48rgetmsg() . . . . . . . . . . . . . . . . . . .
11-51Displaying Error Text in a Windows Environment . . . . .
11-54
A Program That Uses Exception Handling . . . . . . . . .
11-55Compiling the Program . . . . . . . . . . . . . . 11-55Guide
to the getdiag.ec File . . . . . . . . . . . . . 11-56Guide to the
exp_chk.ec File . . . . . . . . . . . . . 11-59
Chapter 12 Working with the Database ServerThe Client-Server
Architecture of ESQL/C Applications . . . . 12-3The Client-Server
Connection . . . . . . . . . . . . . . 12-5
Sources of Connection Information on a UNIX OperatingSystem . .
. . . . . . . . . . . . . . . 12-6
Sources of Connection Information in a WindowsEnvironment . . .
. . . . . . . . . . . . 12-7
Connecting to a Database Server . . . . . . . . . . .
12-15Identifying the Database Server . . . . . . . . . . . .
12-23
Interacting with the Database Server . . . . . . . . . . .
12-26Determining Features of the Database Server . . . . . . .
12-26Switching Between Multiple Database Connections . . . . .
12-28Identifying an Explicit Connection. . . . . . . . . . .
12-30
RMIX-ESQL/C Programmer’s Manual
-
Obtaining Available Databases . . . . . . . . . . . .
12-32Checking the Status of the Database Server . . . . . . . .
12-32Detaching from a Connection . . . . . . . . . . . . .
12-32Interrupting an SQL Request . . . . . . . . . . . . .
12-33Terminating a Connection . . . . . . . . . . . . . . 12-40
Optimized Message Transfers . . . . . . . . . . . . . .
12-41Restrictions on Optimized Message Transfers . . . . . . .
12-41Enabling Optimized Message Transfers . . . . . . . . .
12-42Error Handling with Optimized Message Transfers . . . . .
12-44
Using Database Server Control Functions . . . . . . . . . .
12-46ifx_getcur_conn_name() . . . . . . . . . . . . . . .
12-47sqgetdbs(). . . . . . . . . . . . . . . . . . . .
12-48sqlbreak() . . . . . . . . . . . . . . . . . . . .
12-51sqlbreakcallback() . . . . . . . . . . . . . . . . .
12-53sqldetach() . . . . . . . . . . . . . . . . . . .
12-56sqldone() . . . . . . . . . . . . . . . . . . . .
12-63sqlexit() . . . . . . . . . . . . . . . . . . . .
12-64sqlsignal(). . . . . . . . . . . . . . . . . . . .
12-65sqlstart() . . . . . . . . . . . . . . . . . . . . 12-67
The timeout Program . . . . . . . . . . . . . . . . .
12-69Compiling the Program . . . . . . . . . . . . . . . 12-69Guide
to the timeout.ec File . . . . . . . . . . . . . 12-70Example
Output . . . . . . . . . . . . . . . . . 12-88
Using ESQL/C Connection Library Functions in a
WindowsEnvironment . . . . . . . . . . . . . . . . . 12-92
GetConnect(). . . . . . . . . . . . . . . . . . .
12-94ReleaseConnect() . . . . . . . . . . . . . . . . .
12-97SetConnect() . . . . . . . . . . . . . . . . . . . 12-99
Chapter 13 Using Informix LibrariesChoosing a Version of the
Informix General Libraries . . . . . . 13-5
The Informix General Libraries . . . . . . . . . . . . 13-5The
esql Command . . . . . . . . . . . . . . . . 13-6Linking Static
Informix General Libraries . . . . . . . . . 13-7Linking Shared
Informix General Libraries . . . . . . . . 13-8Choosing Between
Shared and Static Versions . . . . . . . 13-10
Compatibility of Pre-existing ESQL/C Applications withCurrent
Library Versions . . . . . . . . . . . . . 13-12
Using the ifx_getversion Utility . . . . . . . . . . . .
13-13Checking the API Version of a Library . . . . . . . . . .
13-14
Table of Contents xiii
-
xiv INFO
Creating Thread-Safe ESQL/C Applications . . . . . . . . .
13-16Characteristics of Thread-Safe ESQL/C Code . . . . . . .
13-17Programming a Thread-Safe ESQL/C Application . . . . .
13-17Linking Thread-Safe Libraries . . . . . . . . . . . .
13-26
Using ESQL/C Thread-Safe Decimal Functions . . . . . . . .
13-30ifx_dececvt(), ifx_decfcvt() . . . . . . . . . . . . .
13-31
A Sample Thread-Safe Program . . . . . . . . . . . . .
13-33Source Listing . . . . . . . . . . . . . . . . . . 13-33Sample
Output . . . . . . . . . . . . . . . . . 13-39
Creating a Dynamic Thread Library on UNIX OperatingSystems . . .
. . . . . . . . . . . . . . . 13-40
Data Types . . . . . . . . . . . . . . . . . . .
13-43Registering the Dynamic Thread Functions. . . . . . . .
13-47Setting the $THREADLIB Environment Variable . . . . . .
13-50Creating the Shared Library . . . . . . . . . . . . .
13-50Compiling with the -thread and -l Preprocessor Options . . .
13-51
Section III Dynamic SQL
Chapter 14 Using Dynamic SQLUsing Dynamic SQL . . . . . . . . .
. . . . . . . . 14-4
Assembling and Preparing the SQL Statement. . . . . . .
14-5Executing the SQL Statement . . . . . . . . . . . .
14-10Freeing Resources . . . . . . . . . . . . . . . . 14-13
Using a Database Cursor . . . . . . . . . . . . . . .
14-14Receiving More Than One Row . . . . . . . . . . . .
14-14Sending More Than One Row . . . . . . . . . . . . 14-18Naming
the Cursor . . . . . . . . . . . . . . . . 14-19Optimizing Cursor
Execution . . . . . . . . . . . . 14-20
Optimizing OPEN, FETCH, and CLOSE . . . . . . . . . .
14-35Restrictions on OPTOFC . . . . . . . . . . . . . .
14-36Enabling the OPTOFC Feature . . . . . . . . . . . . 14-37
Using OPTOFC and Deferred-PREPARE Together . . . . . . .
14-38SQL Statements That Are Known at Compile Time . . . . . .
14-40
Executing Non-SELECT Statements . . . . . . . . . .
14-40Executing SELECT Statements . . . . . . . . . . . .
14-43Executing User-Defined Routines in Universal Server . . . .
14-46Executing Statements with Input Parameters . . . . . . .
14-51
SQL Statements That Are Not Known at Compile Time . . . . .
14-58
RMIX-ESQL/C Programmer’s Manual
-
Chapter 15 Determining SQL StatementsUsing Dynamic-Management
Structures . . . . . . . . . . 15-4
A System-Descriptor Area . . . . . . . . . . . . . . 15-5An
sqlda Structure. . . . . . . . . . . . . . . . . 15-10
Using the DESCRIBE Statement . . . . . . . . . . . . .
15-14Determining Statement Type . . . . . . . . . . . . .
15-16Determining the Data Type of a Column . . . . . . . . .
15-19Checking for a WHERE Clause . . . . . . . . . . . . 15-22
Determining Statement Information at Runtime . . . . . . . .
15-22Handling an Unknown Select List . . . . . . . . . . .
15-23Handling an Unknown Column List . . . . . . . . . .
15-24Determining Unknown Input Parameters . . . . . . . . .
15-25Determining Return Values Dynamically . . . . . . . . .
15-26Handling Statements That Contain User-Defined
Data Types . . . . . . . . . . . . . . . . 15-27Using a Fetch
Array . . . . . . . . . . . . . . . . . . 15-33
Allocating Memory for the Fetch Arrays . . . . . . . . .
15-37Obtaining Values from Fetch Arrays . . . . . . . . . .
15-42Freeing Memory for a Fetch Array . . . . . . . . . . .
15-45
Chapter 16 Using a System-Descriptor AreaManaging a
System-Descriptor Area . . . . . . . . . . . . 16-4
Allocating Memory for a System-Descriptor Area . . . . . .
16-5Initializing the System-Descriptor Area . . . . . . . . .
16-6Assigning and Obtaining Values from a System-Descriptor
Area . . . . . . . . . . . . . . . . . . 16-8Specifying Input
Parameter Values . . . . . . . . . . . 16-10Putting Column Values
into a System-Descriptor Area . . . . 16-11Freeing Memory Allocated
to a System-Descriptor Area. . . . 16-12
Using a System-Descriptor Area . . . . . . . . . . . . .
16-13Handling an Unknown Select List . . . . . . . . . . . . .
16-13
Executing a SELECT That Returns Multiple Rows . . . . . .
16-15Executing a Singleton SELECT . . . . . . . . . . . . 16-22
Handling Unknown Return Values . . . . . . . . . . . .
16-22Executing a Noncursor Function . . . . . . . . . . . .
16-23Executing a Cursor Function . . . . . . . . . . . . .
16-28
Handling an Unknown Column List . . . . . . . . . . . .
16-29Executing a Simple Insert . . . . . . . . . . . . . .
16-30Executing an INSERT That Is Associated with a Cursor . . . .
16-35
Table of Contents xv
-
xvi INFO
Handling a Parameterized SELECT Statement . . . . . . . .
16-36Executing a Parameterized SELECT That Returns Multiple
Rows. . . . . . . . . . . . . . . . . . 16-37Executing a
Parameterized Singleton SELECT . . . . . . . 16-43
Handling a Parameterized User-Defined Routine . . . . . . .
16-43Executing a Parameterized Function . . . . . . . . . .
16-44Executing a Parameterized Procedure . . . . . . . . .
16-45
Handling a Parameterized UPDATE or DELETE Statement . . .
16-46The dyn_sql Program . . . . . . . . . . . . . . . . .
16-47
Compiling the Program . . . . . . . . . . . . . . 16-47Guide to
the dyn_sql.ec File . . . . . . . . . . . . . 16-48
Chapter 17 Using an sqlda StructureManaging an sqlda Structure .
. . . . . . . . . . . . . 17-4
Defining an sqlda Structure . . . . . . . . . . . . .
17-5Allocating Memory for the sqlda Structure . . . . . . . .
17-6Initializing the sqlda Structure . . . . . . . . . . . .
17-7Allocating Memory for Column Data . . . . . . . . . .
17-10Assigning and Obtaining Values from an sqlda Structure . . .
17-13Specifying Input Parameter Values . . . . . . . . . .
17-14Putting Column Values into an sqlda Structure . . . . . .
17-14Freeing Memory Allocated to an sqlda Structure . . . . . .
17-15
Using an sqlda Structure . . . . . . . . . . . . . . .
17-16Handling an Unknown Select List . . . . . . . . . . . .
17-17
Executing a SELECT That Returns Multiple Rows . . . . .
17-18Executing a Singleton SELECT . . . . . . . . . . . . 17-26
Handling Unknown Return Values . . . . . . . . . . . .
17-26Executing a Noncursor Function . . . . . . . . . . .
17-28Executing a Cursor Function . . . . . . . . . . . . .
17-28
Handling an Unknown Column List . . . . . . . . . . .
17-30Executing a Simple Insert . . . . . . . . . . . . . .
17-31Executing an INSERT That Is Associated with a Cursor . . .
17-31
Handling a Parameterized SELECT Statement . . . . . . . .
17-32Executing a Parameterized SELECT That Returns Multiple
Rows. . . . . . . . . . . . . . . . . . 17-34Executing a
Parameterized Singleton SELECT . . . . . . . 17-41
Handling a Parameterized User-Defined Routine . . . . . . .
17-41Executing a Parameterized Function . . . . . . . . . .
17-42Executing a Parameterized Procedure . . . . . . . . .
17-42
Handling a Parameterized UPDATE or DELETE Statement . . .
17-43
RMIX-ESQL/C Programmer’s Manual
-
Appendix A List of ESQL/C Library Functions
Appendix B The Demonstration Database
Index
Table of Contents xvii
-
Introduction
Introduction
About This Manual . . . . . . . . . . . . . . . . . . . 3Types
of Users . . . . . . . . . . . . . . . . . . . 3Software
Dependencies . . . . . . . . . . . . . . . . 4Assumptions About
Your Locale . . . . . . . . . . . . . 4Demonstration Database . . .
. . . . . . . . . . . . 5
Major Features . . . . . . . . . . . . . . . . . . . . 5
Documentation Conventions . . . . . . . . . . . . . . .
6Typographical Conventions . . . . . . . . . . . . . . 7Icon
Conventions . . . . . . . . . . . . . . . . . . 8
Comment Icons . . . . . . . . . . . . . . . . . 8Feature,
Product, and Platform Icons . . . . . . . . . . 9
Command-Line Conventions . . . . . . . . . . . . . . 10How to
Read a Command-Line Diagram . . . . . . . . 12
Additional Documentation . . . . . . . . . . . . . . . .
12On-Line Manuals . . . . . . . . . . . . . . . . . . 13Printed
Manuals . . . . . . . . . . . . . . . . . . 13Error Message Files .
. . . . . . . . . . . . . . . . 13Documentation Notes, Release
Notes, Machine Notes . . . . . 14
Compliance with Industry Standards . . . . . . . . . . . .
15
Informix Welcomes Your Comments . . . . . . . . . . . . . 15
-
2 INFOR
MIX-ESQL/C Programmer’s Manual
-
Read this introduction for an overview of the
informationprovided in this manual and for an understanding of the
documentationconventions used.
About This ManualThis manual explains how to use
INFORMIX-ESQL/C, the Informix imple-mentation of embedded
Structured Query Language (SQL) for C, to createclient applications
with database-management capabilities. This manual is acomplete
guide to the features of ESQL/C that enable you to interact with
thedatabase server, access databases, manipulate the data in your
program, andcheck for errors.
This manual progresses from general topics to more advanced
programmingtechniques and examples.
Types of UsersThis manual is for C programmers who want to use
ESQL/C to embed SQLstatements in their programs. The manual assumes
that you know Cprogramming and are familiar with the structure of
relational databases.
If you have limited experience with relational databases, SQL,
or youroperating system, see the Getting Started manual for your
database server fora list of supplementary manuals.
Introduction 3
-
Software Dependencies
Software DependenciesThis manual assumes that you are using
INFORMIX-ESQL/C, Version 9.13, oneither a Windows NT, Windows 95,
or UNIX platform. In addition, you mustuse one of the following
database servers:
■ INFORMIX-OnLine Dynamic Server, Version 7.2x
■ INFORMIX-OnLine Workgroup Server, Version 7.2x
■ INFORMIX-OnLine XPS, Version 8.1x
■ INFORMIX-SE, Version 7.2x
■ INFORMIX-Universal Server, Version 9.1x
Assumptions About Your LocaleInformix products can support many
languages, cultures, and code sets. Allculture-specific information
is brought together in a single environment,called a GLS (Global
Language Support) locale.
This manual assumes that you are using the default locale,
en_us.8859-1. Thislocale supports U.S. English format conventions
for dates, times, andcurrency. In addition, this locale supports
the ISO 8859-1 code set, whichincludes the ASCII code set plus many
8-bit characters such as é, è, and ñ.
If you plan to use nondefault characters in your data or your
SQL identifiers,or if you want to conform to the nondefault
collation rules of character data,you need to specify the
appropriate nondefault locale(s). For instructions onhow to specify
a nondefault locale, additional syntax, and other consider-ations
related to GLS locales, see the INFORMIX-GLS Programmer’s Manualand
the Informix Guide to GLS Functionality.
4 INFORMIX-ESQL/C Programmer’s Manual
-
Demonstration Database
Demonstration DatabaseYour Informix software includes a
demonstration database called stores7that contains information
about a fictitious wholesale sporting-goodsdistributor. Informix
includes source files for INFORMIX-ESQL/C demon-stration programs
that access and manipulate the data stored in stores7. Mostof the
examples in this manual are based on the stores7
demonstrationdatabase.
For information on how to install stores7 and access the code
examples, seeAppendix B, “The Demonstration Database,” of this
manual.
Major FeaturesThe Introduction to each Informix product manual
contains a list of majorfeatures for that product. Major features
for Informix products also appear inrelease notes.
Informix has implemented the following major new features in
Version 9.13of INFORMIX-ESQL/C:
■ The ability to have the C preprocessor run prior to the esql
prepro-cessor. This ability makes the following functionalities
possible:
❑ The ability to declare any valid C syntax inside ESQL/C
BEGINDECLARE-END DECLARE sections
❑ The ability to declare ANSI-C style function parameters as
hostvariables
❑ Ability to define host variables with #define and typedef
state-ments defined in either C library header files or in
user-createdC language header files
■ Support for user-defined dynamic thread libraries
Introduction 5
-
Documentation Conventions
■ The following functions:
❑ ifx_cl_card()
Returns the number of elements in a collection
❑ ifx_lo_from_buffer()
Copies bytes from a user-defined buffer into smart large
object
❑ ifx_lo_release()
Releases resources associated with a temporary smart
largeobject
❑ ifx_lo_to_buffer()
Copies bytes from smart large object into a user-defined
buffer
■ The lvarchar pointer variable, which enables you to insert or
selectopaque type columns that can be represented in a character
stringformat and which can vary in size from one row in the table
toanother
Documentation ConventionsThis section describes the conventions
that this manual uses. These conven-tions make it easier to gather
information from this and other Informixmanuals.
The following conventions are covered:
■ Typographical conventions
■ Icon conventions
■ Command-line conventions
6 INFORMIX-ESQL/C Programmer’s Manual
-
Typographical Conventions
Typographical ConventionsThis manual uses the following standard
set of conventions to introduce newterms, illustrate screen
displays, describe command syntax, and so forth.
Tip: When you are instructed to “enter” characters or to
“execute” a command,immediately press RETURN after the entry. When
you are instructed to “type” thetext or to “press” other keys, no
RETURN is required.
Convention Meaning
KEYWORD All keywords appear in uppercase letters in a serif
font.
italics Within text, new terms and emphasized words appear in
italics.Within syntax diagrams, values that you are to specify
appearin italics.
boldface Identifiers (names of classes, objects, constants,
events,functions, program variables, forms, labels, and
reports),environment variables, database names, filenames,
tablenames, column names, icons, menu items, command names,and
other similar terms appear in boldface.
monospace Information that the product displays and information
that youenter appear in a monospace typeface.
KEYSTROKE Keys that you are to press appear in uppercase letters
in a sansserif font.
♦ This symbol indicates the end of feature-, product-,
platform-,or compliance-specific information.
Introduction 7
-
Icon Conventions
Icon ConventionsThroughout the documentation, you will find text
that is identified by severaldifferent types of icons. This section
describes these icons.
Comment Icons
Comment icons identify warnings, important notes, or tips. This
informationis always displayed in italics.
Icon Description
The warning icon identifies vital instructions, cautions,
orcritical information.
The important icon identifies significant information aboutthe
feature or operation that is being described.
The tip icon identifies additional details or shortcuts for
thefunctionality that is being described.
8 INFORMIX-ESQL/C Programmer’s Manual
-
Icon Conventions
Feature, Product, and Platform Icons
Feature, product, and platform icons identify paragraphs that
containfeature-, product-, or platform-specific information.
Icon Description
Identifies information that is specific to a user-defined
routine(UDR) that is written in an external language (such as
C)
Identifies information that is specific to the Informix
GlobalLanguage Support (GLS) feature.
Identifies information that is specific to
INFORMIX-UniversalServer.
Identifies information that is specific to
INFORMIX-OnLineDynamic Server.
Identifies information that is specific to
INFORMIX-OnLineWorkgroup Server.
Identifies information that is specific to INFORMIX-SE.
Identifies information that is specific to a user-defined
routine(UDR) that is written in Informix Stored Procedure
Language.
Identifies information that is specific to the UNIX
operatingsystem.
Identifies information that is specific to the Windows
NTenvironment.
Identifies information that is specific to the Windows
95environment.
Identifies information that is specific to both Windows NT
andWindows 95 environments.
Identifies information that is specific to
INFORMIX-OnLineXPS.
Identifies functionality that conforms to X/Open specifica-tions
for dynamic SQL. This functionality is available whenyou compile
your SQL API with the -xopen flag.
EXT
GLS
IUS
ODS
OWS
SE
SPL
UNIX
WIN NT
WIN 95
WIN NT/95
XPS
X/O
Introduction 9
-
Command-Line Conventions
These icons can apply to a row in a table, one or more
paragraphs, or an entiresection. A ♦ symbol indicates the end of
the feature-, product-, or platform-specific information.
Command-Line ConventionsThis section defines and illustrates the
format of commands that are availablein Informix products. These
commands have their own conventions, whichmight include alternative
forms of a command, required and optional partsof the command, and
so forth.
INFORMIX-ESQL/C supports a variety of command-line options. Each
validcommand-line option is illustrated in a diagram in Chapter 1,
“Programmingwith INFORMIX-ESQL/C.”
Each diagram displays the sequences of required and optional
elements thatare valid in a command. A diagram begins at the
upper-left corner with acommand. It ends at the upper-right corner
with a vertical line. Betweenthese points, you can trace any path
that does not stop or back up. Each pathdescribes a valid form of
the command. You must supply a value for wordsthat are in
italics.
You might encounter one or more of the following elements on a
command-line path.
Element Description
command This required element is usually the product name
orother short word that invokes the product or calls thecompiler or
preprocessor script for a compiled Informixproduct. It might appear
alone or precede one or moreoptions. You must spell a command
exactly as shownand use lowercase letters.
variable A word in italics represents a value that you
mustsupply, such as a database, file, or program name. A
tablefollowing the diagram explains the value.
-flag A flag is usually an abbreviation for a function, menu,
oroption name or for a compiler or preprocessor argument.You must
enter a flag exactly as shown, including thepreceding hyphen.
(1 of 2)
10 INFORMIX-ESQL/C Programmer’s Manual
-
Command-Line Conventions
.ext A filename extension, such as .sql or .cob, might followa
variable that represents a filename. Type this extensionexactly as
shown, immediately after the name of the file.The extension might
be optional in certain products.
( . , ; + * - / ) Punctuation and mathematical notations are
literalsymbols that you must enter exactly as shown.
' ' Single quotes are literal symbols that you must enter
asshown.
A reference in a box represents a subdiagram. Imaginethat the
subdiagram is spliced into the main diagram atthis point. When a
page number is not specified, thesubdiagram appears on the same
page.
A shaded option is the default action.
Syntax within a pair of arrows indicates a subdiagram.
The vertical line terminates the command.
A branch below the main path indicates an optionalpath. (Any
term on the main path is required, unlessa branch can circumvent
it.)
A loop indicates a path that you can repeat. Punctuationalong
the top of the loop indicates the separator symbolfor list
items.
A gate ( ) on a path indicates that you can only usethat path
the indicated number of times, even if it is partof a larger loop.
Here you can specify size no more thanthree times within this
statement segment.
Element Description
(2 of 2)
Privilegesp. 5-17
Privileges
ALL
ON
-f OFF
variable
,
size3
, 3
Introduction 11
-
Additional Documentation
How to Read a Command-Line Diagram
Figure 1 shows a command-line diagram that uses some of the
elements thatare listed in the previous table.
To construct a command correctly, start at the top left with the
command.Then follow the diagram to the right, including the
elements that you want.The elements in the diagram are case
sensitive.
Figure 1 diagrams the following steps:
1. Type the word setenv.
2. Type the word INFORMIXC.
3. Supply either a compiler name or pathname.
After you choose compiler or pathname, you come to the
terminator.Your command is complete.
4. Press RETURN to execute the command.
Additional DocumentationFor additional information, you might
want to refer to the following types ofdocumentation:
■ On-line manuals
■ Printed manuals
■ Error message files
■ Documentation notes, release notes, and machine notes
Figure 1Example of a Command-Line Diagram
pathname
compilersetenv INFORMIXC
pathname
compilersetenv INFORMIXC
12 INFORMIX-ESQL/C Programmer’s Manual
-
On-Line Manuals
On-Line ManualsAn Answers OnLine CD that contains Informix
manuals in electronic formatis provided with your Informix
products. You can install the documentationor access it directly
from the CD. For information about how to install, read,and print
on-line manuals, see the installation insert that
accompaniesAnswers OnLine.
Printed ManualsTo order printed manuals, call 1-800-331-1763 or
send email [email protected].
Please provide the following information:
■ The documentation that you need
■ The quantity that you need
■ Your name, address, and telephone number
Error Message FilesInformix software products provide ASCII
files that contain all of theInformix error messages and their
corrective actions. The finderr utilitydisplays these error
messages on the screen. See the Introduction to theInformix Error
Messages manual for a detailed description of these
errormessages.
To read the error messages in the ASCII file, Informix provides
scripts that letyou display error messages on the screen (finderr)
or print formatted errormessages (rofferr). For a detailed
description of these scripts, see theIntroduction to the Informix
Error Messages manual. ♦
Informix Find Error is a graphical tool. This utility has been
created withMicrosoft help facilities. For more information, see
the Introduction to theInformix Error Messages manual. ♦
UNIX
WIN NT/95
Introduction 13
-
Documentation Notes, Release Notes, Machine Notes
Documentation Notes, Release Notes, Machine NotesIn addition to
printed documentation, the following on-line files supplementthe
information in this manual. For UNIX, these files are located in
the$INFORMIXDIR/release/en_us/0333 directory. For Windows, these
files arelocated in the $INFORMIXDIR\release\en_us\04e4
directory.
Please examine these files because they contain vital
information aboutapplication and performance issues.
On-Line File Purpose
ESQLCDOC_9.1 The documentation notes file describes features
that are notcovered in this manual or that have been modified since
publi-cation. For Windows, click the Documentation Notes icon.
CLIENTS_9.1 The CLIENTS_2.0 file lists the release-notes files
for the 2.0 ClientSDK. These release-notes files describe feature
differences fromearlier versions of Informix products and how these
differencesmight affect current products. These files also contain
infor-mation about any known problems and their workarounds.
Inaddition, the file for ESQL/C contains a section on limits
thatdescribes the maximum values for INFORMIX-ESQL/C. ForWindows,
click the Release Notes icon.
ESQLC_9.1 The machine notes file describes any special actions
that arerequired to configure and use Informix products on
yourcomputer. ♦
UNIX
14 INFORMIX-ESQL/C Programmer’s Manual
-
Compliance with Industry Standards
Compliance with Industry StandardsThe American National
Standards Institute (ANSI) has established a set ofindustry
standards for SQL. Informix SQL-based products are fully
compliantwith SQL-92 Entry Level (published as ANSI X3.135-1992),
which is identicalto ISO 9075:1992, on Informix database servers.
In addition, many features ofInformix database servers comply with
the SQL-92 Intermediate and FullLevel and X/Open SQL CAE (common
applications environment) standards.
Informix Welcomes Your CommentsPlease tell us what you like or
dislike about our manuals. To help us withfuture versions of our
manuals, we want to know about corrections or clari-fications that
you would find useful. Include the following information:
■ The name and version of the manual that you are using
■ Any comments that you have about the manual
■ Your name, address, and phone number
Write to us at the following address:
Informix Software, Inc.SCT Technical Publications Department4100
Bohannon DriveMenlo Park, CA 94025
If you prefer to send email, our address is:
[email protected]
Or send a facsimile to the Informix Technical Publications
Department at:
650-926-6571
We appreciate your feedback.
Introduction 15
-
on I
What Is INFORMIX-ESQL/C?
Sect
i
-
1Chapter
Programming with INFORMIX-ESQL/C
What Is INFORMIX-ESQL/C? . . . . . . . . . . . . . . . 1-5ESQL/C
Executable Files for Windows . . . . . . . . . . 1-6ESQL/C Library
Functions. . . . . . . . . . . . . . . 1-7Creating an ESQL/C
Program . . . . . . . . . . . . . 1-8Compiling an ESQL/C Program .
. . . . . . . . . . . . 1-9
ESQL/C Preprocessor . . . . . . . . . . . . . . . 1-9C
Preprocessor and Compiler . . . . . . . . . . . . 1-10
Default Compilation Order. . . . . . . . . . . . . . .
1-11Running the C Preprocessor First . . . . . . . . . . . .
1-12
Using ESQL/C Preprocessor Directives . . . . . . . . . . . .
1-12The include Directive. . . . . . . . . . . . . . . . . 1-13The
define and undef Directives . . . . . . . . . . . . . 1-14The
ifdef, ifndef, elif, else, and endif Directives . . . . . . . .
1-16
Embedding SQL Statements. . . . . . . . . . . . . . . .
1-17Handling Case Sensitivity in Embedded SQL Statements . . . .
1-18Using Quotes and Escape Characters . . . . . . . . . . .
1-19Adding Comments . . . . . . . . . . . . . . . . .
1-21Specifying Host Variables . . . . . . . . . . . . . . .
1-21Using ESQL/C Header Files . . . . . . . . . . . . . . 1-22
Declaring Function Prototypes . . . . . . . . . . . .
1-25Including Header Files . . . . . . . . . . . . . . . 1-26
Declaring and Using Host Variables in SQL Statements . . . . . .
1-27Declaring a Host Variable . . . . . . . . . . . . . . .
1-27
Host-Variable Names . . . . . . . . . . . . . . .
1-28Host-Variable Data Types . . . . . . . . . . . . . .
1-28Initial Host-Variable Values . . . . . . . . . . . . .
1-29Scope of Host Variables . . . . . . . . . . . . . . 1-29Sample
Host-Variable Declarations . . . . . . . . . . 1-31
-
1-2 INFO
Assigning a Value to a Host Variable . . . . . . . . . . .
1-32SQL Identifiers. . . . . . . . . . . . . . . . . . 1-32Null
Values in Host Variables. . . . . . . . . . . . . 1-35
Using Host Variables in Data Structures . . . . . . . . . .
1-36Arrays of Host Variables . . . . . . . . . . . . . . 1-36C
Structures as Host Variables . . . . . . . . . . . . 1-37C typedef
Expressions as Host Variables . . . . . . . . . 1-38Pointers as
Host Variables . . . . . . . . . . . . . . 1-39Function Parameters
as Host Variables . . . . . . . . . 1-40
Using Indicator Variables . . . . . . . . . . . . . . .
1-42Values in Indicator Variables . . . . . . . . . . . . .
1-42Declaring Indicator Variables . . . . . . . . . . . . .
1-44Associating an Indicator Variable with a Host Variable . . . .
1-45An Example Using Indicator Variables . . . . . . . . . 1-46
Using the esql Command . . . . . . . . . . . . . . . . .
1-47Requirements for Using esql . . . . . . . . . . . . . .
1-48Syntax of the esql Command . . . . . . . . . . . . . . 1-48
The esql Command for UNIX. . . . . . . . . . . . . 1-49The esql
Command for Windows Environments . . . . . . 1-52
Options That Affect Preprocessing . . . . . . . . . . . .
1-58Checking the Version Number . . . . . . . . . . . .
1-58Associating Options with Files . . . . . . . . . . . .
1-58Preprocessing Without Compiling or Linking . . . . . . .
1-58Generating Thread-Safe Code . . . . . . . . . . . .
1-59Checking for ANSI-Standard SQL Syntax . . . . . . . .
1-59Defining and Undefining Definitions While
Preprocessing . . . . . . . . . . . . . . . 1-60Checking for
Missing Indicator Variables . . . . . . . . 1-62Naming the Location
of Include Files . . . . . . . . . . 1-62Numbering Lines . . . . .
. . . . . . . . . . . . 1-64Setting the Scope of Cursor Names and
Statement IDs . . . . 1-64Redirecting Errors and Warnings . . . . .
. . . . . . 1-64Suppressing Warnings . . . . . . . . . . . . . . .
1-65Using X/Open Standards . . . . . . . . . . . . . . 1-65
Running the C Preprocessor Before the ESQL/CPreprocessor . . . .
. . . . . . . . . . . . . . 1-66Options for Running the C
Preprocessor First . . . . . . . 1-67CPFIRST Environment Variable .
. . . . . . . . . . . 1-67The Order of Compilation When the C
Preprocessor
Runs First . . . . . . . . . . . . . . . . . 1-68
RMIX-ESQL/C Programmer’s Manual
-
Defining Host Variables Based on C #definesand typedefs . . . .
. . . . . . . . . . . . 1-69
Allowing All Valid C Declaration Syntax Inside the EXECSQL
Declare Section . . . . . . . . . . . . . . 1-71
Excluding Statements Inside C Header Files . . . . . . . .
1-71SQL Keyword Protection . . . . . . . . . . . . . . . 1-72SQL
Keyword Protection and the $ Symbol . . . . . . . . 1-72
Preprocessor Options Specific to Windows Environments . . . . .
1-73Line Wrapping . . . . . . . . . . . . . . . . . . 1-73Changing
Error and Warning Displays . . . . . . . . . . 1-74Setting Tab
Stops . . . . . . . . . . . . . . . . . 1-74
Compiling and Linking Options of the esql Command . . . . . . .
1-75Syntax of the Compiling/Linking Options for UNIX . . . . . .
1-75
Naming the Executable File on UNIX . . . . . . . . . .
1-76Passing Options to the C Compiler . . . . . . . . . . .
1-76Specifying a Particular C Compiler . . . . . . . . . . .
1-77
Syntax of the Compiling/Linking Options for WindowsEnvironments
. . . . . . . . . . . . . . . . . . 1-77Naming the Executable File
in Windows
Environments . . . . . . . . . . . . . . . . 1-79Passing Options
to the C Compiler in Windows
Environments . . . . . . . . . . . . . . . . 1-80Specifying a
Particular C Compiler in Windows
Environments . . . . . . . . . . . . . . . . 1-80Compiling
Without Linking. . . . . . . . . . . . . . 1-80
Special Compile Options for Windows Environments . . . . . .
1-81Using a Project File . . . . . . . . . . . . . . . . .
1-81Creating a Response File . . . . . . . . . . . . . . .
1-82Implicit Options Invoked by the esql Preprocessor in
Windows Environments . . . . . . . . . . . . 1-82General Options
That Affect Linking . . . . . . . . . . . . 1-86
Linking Other C Source and Object Files . . . . . . . . .
1-86Specifying Versions of Informix General Libraries . . . . . .
1-87
Special Linking Options for Windows Environments . . . . . .
1-87Passing Arguments to the Linker . . . . . . . . . . . .
1-87Passing Arguments to the Resource Compiler . . . . . . .
1-88ESQL/C Dynamic Link Libraries . . . . . . . . . . . . 1-88Using
the Same Runtime Routines for Version
Independence . . . . . . . . . . . . . . . . 1-89
Programming with INFORMIX-ESQL/C 1-3
-
1-4 INFO
Windows Operating System Processor Options Available to theesql
Command. . . . . . . . . . . . . . . . . . 1-90Syntax of the
Options for Windows Environments . . . . . 1-90
Accessing the ESQL Client-Interface DLL in WindowsEnvironments .
. . . . . . . . . . . . . . . . . 1-94Accessing the Import Library.
. . . . . . . . . . . . 1-95Locating a DLL . . . . . . . . . . . .
. . . . . 1-95Building an Application DLL. . . . . . . . . . . . .
1-96
Setting and Retrieving Environment Variables in
WindowsEnvironments . . . . . . . . . . . . . . . . . . 1-97
ifx_putenv() . . . . . . . . . . . . . . . . . . . .
1-100ifx_getenv() . . . . . . . . . . . . . . . . . . . .
1-102InetLogin Structure . . . . . . . . . . . . . . . . .
1-103
Fields of the InetLogin Structure . . . . . . . . . . .
1-104InetLogin Field Values . . . . . . . . . . . . . . .
1-109Precedence of Configuration Values . . . . . . . . . .
1-111
Using Host Variables in Windows Environments . . . . . . . .
1-112Declaring Variables with Non-ANSI Storage-Class
Modifiers . . . . . . . . . . . . . . . . . . . 1-112Using
Global ESQL/C Variables . . . . . . . . . . . . . 1-115
A Sample INFORMIX-ESQL/C Program . . . . . . . . . . .
1-116Compiling the demo1 Program . . . . . . . . . . . . .
1-116Guide to demo1.ec File . . . . . . . . . . . . . . . .
1-116
RMIX-ESQL/C Programmer’s Manual
-
This chapter covers the following topics:■ What is
INFORMIX-ESQL/C?
■ Using ESQL/C preprocessor directives
■ Embedding SQL statements in C programs
■ Declaring and using host variables in SQL statements
■ Preprocessing and compiling an ESQL/C program
The last section of this chapter, “A Sample INFORMIX-ESQL/C
Program” onpage 1-116, presents an annotated sample program that is
called demo1. Thedemo1 sample program illustrates the basic
programming concepts that thischapter introduces.
What Is INFORMIX-ESQL/C?ESQL/C is an SQL application programming
interface (API) that enables you toembed Structured Query Language
(SQL) statements directly into aC program. The ESQL/C preprocessor,
which the esql command calls,converts each SQL statement and all
Informix-specific code to C.
ESQL/C consists of the following software components:
■ The ESQL/C libraries of C functions, which provide access to
thedatabase server
■ The ESQL/C header files, which provide definitions for the
datastructures, constants, and macros useful to the ESQL/C
program
■ The esql command, which manages the processing of the
sourcecode to convert a C file that contains SQL statements into an
objectfile
Programming with INFORMIX-ESQL/C 1-5
-
ESQL/C Executable Files for Windows
■ The finderr utility on the UNIX system and the INFORMIX
FINDERROR Windows-based utility that enable you to obtain
informationabout Informix-specific error messages.
■ The Informix GLS locale and code-set-conversion files, which
providelocale-specific information. For more information on these
files, seethe Informix Guide to GLS Functionality. ♦
■ The ESQL client-interface dynamic link libraries (DLLs), which
enablean ESQL/C application to run in a Windows environment. ♦
ESQL/C Executable Files for WindowsFor Windows environments, the
ESQL/C product contains the followingadditional executable
files:
■ The Setnet32 utility is a Windows-based utility that enables
you toset configuration information. For more information, see the
InformixClient Products Installation Guide for Windows.
■ The ILOGIN utility is a demonstration program that displays
adialog box with fields for the connection parameters, for testing
aconnection to the database server (uses the stores7 database).
■ The REGCOPY utility is a Windows-based utility that makes
anESQL/C program into a Windows NT service. For more
information,see the Informix Client Products Installation Guide for
Windows. ♦
■ The ESQLMF.EXE multibyte filter changes escape characters
inmultibyte strings into hexadecimal literals.
These ESQL/C executable files are located in the
%INFORMIXDIR%\bin,%INFORMIXDIR%\lib, and %INFORMIXDIR%\demo
directories.%INFORMIXDIR% represents the value of the INFORMIXDIR
environmentvariable. ♦
GLS
WIN NT/95
WIN NT/95
WIN NT
1-6 INFORMIX-ESQL/C Programmer’s Manual
-
ESQL/C Library Functions
ESQL/C Library FunctionsThe ESQL/C library contains a set of C
functions that you can use in yourapplication. These functions fall
into the following categories:
■ Data type alignment library functions provide support for
computer-independent size and alignment information for different
data typesand assist in working with null database values.
■ Character and string library functions provide
character-basedmanipulations such as comparison and copying.
■ DECIMAL library functions support access to DECIMAL
valuesthrough the decimal structure.
■ Formatting functions enable you to specify display formats
fordifferent data types.
■ DATE library functions support access to DATE values.
■ DATETIME and INTERVAL library functions support access to
valuesof these data types through the datetime and interval
structures,respectively.
■ Error message functions provide support for obtaining
andformatting Informix-specific error-message text.
■ Database server control functions enable your application
toimplement such features as cancelling queries and
terminatingconnections.
■ INT8 library functions enable you to access INT8 values
through theint8 structure.
■ Smart-large-object library functions provide a file-like
interface tothe BLOB and CLOB data types. ♦
To access a database server through an ESQL/C application
1. Write embedded SQL statements and calls to ESQL/C
libraryfunctions into your C code to create an ESQL/C program.
2. Convert the ESQL/C program to a C executable file with the
esqlcommand.
3. Repeat step 2 as needed to remove programming errors.
The following sections provide detailed instructions for steps 1
and 2.
IUS
Programming with INFORMIX-ESQL/C 1-7
-
Creating an ESQL/C Program
Creating an ESQL/C ProgramAn ESQL/C source file can contain the
following types of statements:
■ Preprocessor directives
❑ ESQL/C preprocessor directives to create simple macro
defini-tions, include ESQL/C files, and perform conditional
ESQL/Ccompilation
❑ C preprocessor directives to create macro definitions,
includesystem and C source files, and perform conditionalC
compilation
■ Language statements
❑ Embedded SQL statements to communicate with the
databaseserver
❑ C language statements to provide program logic
❑ Host variables to transfer data between the C program and
theSQL statements
For information on C preprocessor directives and C language
statements,refer to a C programming text. This chapter provides an
overview of theESQL/C preprocessor directives (page 1-12), embedded
SQL statements(page 1-17), and host variables (page 1-27).
Your ESQL/C source code filename can have either of the
following forms:
■ esqlc_source.ec
■ esqlc_source .ecp
The particular suffix that your ESQL/C source file has
determines the defaultorder 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 Beforethe ESQL/C
Preprocessor” on page 1-66. ♦
1-8 INFORMIX-ESQL/C Programmer’s Manual
-
Compiling an ESQL/C Program
Compiling an ESQL/C ProgramYou type the esql command to compile
your ESQL/C program. The esqlcommand passes your ESQL/C source file
to the ESQL/C preprocessor and tothe C compiler. It passes along
options that are specific to both the ESQL/Cpreprocessor and the C
compiler to preprocess, compile, and link yourESQL/Cprogram.
ESQL/C Preprocessor
To preprocess, compile, and link a program that contains ESQL/C
statements,you must pass it through the ESQL/C preprocessor. You
use the esqlcommand to run the preprocessor on your ESQL/C source
file and create anexecutable file. The esql command follows these
steps to carry out theconversion:
■ In Stage 1, the ESQL/C preprocessor performs the following
steps:
❑ Incorporates header files into the source file when it
processes allinclude directives ($include and EXEC SQL include
statements)
❑ Creates or removes compile-time definitions when it
processesall define ($define and EXEC SQL define) and undef ($undef
andEXEC SQL undef) directives
■ In Stage 2, the ESQL/C preprocessor processes any
conditionalcompilation directives (ifdef, ifndef, else, elif,
endif) and translatesembedded SQL statements to ESQL/C function
calls and special datastructures.
Stages 1 and 2 mirror the preprocessor and compiler stages of
the Ccompiler. Successful completion of the preprocessing step
yields a Csource file (.c extension). For information about
command-lineoptions that affect the preprocessing step, see
“Options That AffectPreprocessing” on page 1-58.
Programming with INFORMIX-ESQL/C 1-9
-
Compiling an ESQL/C Program
The esql command processor is installed as part of the ESQL/C
product.Before you use esql, make sure that:
■ the filename of the ESQL/C source file has the .ec or the
.ecpextension.
■ the INFORMIXDIR and PATH environment variables are set
correctly.
For information on how to set the INFORMIXDIR and PATHvariables,
see the Client Products Installation Guide for your
operatingsystem.
For a detailed explanation of the syntax of the esql command,
see “Using theesql Command” on page 1-47.
Warning: The C code that the ESQL/C preprocessor generates might
change from onerelease of the product to the next. Therefore, do
not design ESQL/C programs thatdepend on how Informix implements
the functionality and features of the product inthe C code that the
ESQL/C preprocessor generates. Instead, develop your programswith
the functionality and features of the product that this manual
describes.
C Preprocessor and Compiler
The esql command does not itself compile and link the ESQL/C
program.Instead, the C preprocessor preprocesses the C language
preprocessing direc-tives. The C compiler performs the compilation,
and it also calls a link editorto link the C object files. The esql
command calls the C compiler to initiatethis process, but its main
task is to translate ESQL/C code to C code.
Your ESQL/C source file contains commands for the C preprocessor
(direc-tives of the form #directive). In the case of the default
order of compilation,these C directives have no effect on ESQL/C
statements but take effect in theusual way when the C compiler
processes the source file.
If you choose the option of running the C preprocessor on the
ESQL/C sourcefile before the ESQL/C preprocessor, you can use the C
language #define andtypedef directives to define ESQL/C host
variables. For more information, see“Running the C Preprocessor
Before the ESQL/C Preprocessor” onpage 1-66.
1-10 INFORMIX-ESQL/C Programmer’s Manual
-
Default Compilation Order
The C compiler takes the following actions:
■ Compiles the C language statements to object code
■ Links to ESQL/C libraries as well as any other files or
libraries youspecify
■ Creates an executable file
For information about command-line options that affect the
compilation andlinking steps, see “Specifying a Particular C
Compiler” on page 1-77 and“General Options That Affect Linking” on
page 1-86.
Default Compilation OrderOnce you have created an ESQL/C program
file, you run the esql commandon that file. By default, the ESQL/C
preprocessor runs first and translates theembedded SQL statements
in the program into ESQL/C function calls thatcommunicate with the
database server. The ESQL/C preprocessor produces aC source file
and calls the C compiler. The C compiler then preprocesses
andcompiles your source file and links any other C source file,
object file, orlibrary file the same way as any other C program. If
esql does not encountererrors in one of these steps, it generates
an executable file. You can run thecompiled ESQL/C program as you
would any C program. When the programruns, it calls the ESQL/C
library procedures; they set up communicationswith the database
server to carry out the SQL operations.
Figure 1-1 illustrates the process by which an ESQL/C program
becomes anexecutable program.
Figure 1-1Relationship Between INFORMIX-ESQL/C and C
ESQL/C sourceprogram
ESQL/C preprocessorstages 1 and 2
C source programwith SQL statementsand ESQL/C calls
C languagepreprocessorand compiler
Executableprogram
Programming with INFORMIX-ESQL/C 1-11
-
Running the C Preprocessor First
To preprocess, compile, and link a C program that contains
ESQL/C state-ments, you must pass it through the ESQL/C
preprocessor. Use the esqlcommand to preprocess the ESQL/C source
file and create an executable file.The esql command follows these
steps to carry out the conversion:
Important: Keep in mind that with the default order of
compilation, esql handlesESQL/C preprocessor directives before it
calls the C compiler. Therefore, the ESQL/Cdirectives take effect
before the C compiler performs any preprocessing. You cannotaccess
ESQL/C definitions within C preprocessor directives, nor can you
use the Cpreprocessor to perform conditional compilation of ESQL/C
statements.
Running the C Preprocessor FirstWith this release, you can
either let the compilation of your ESQL/C sourcefile follow the
default order or let the C preprocessor run on the source
filefirst, and then pass that file to the ESQL/C preprocessor. This
feature is usefulin case you want your ESQL/C program to access C
preprocessor directives.For more information on this option, see
“Running the C Preprocessor Beforethe ESQL/C Preprocessor” on page
1-66.
Using ESQL/C Preprocessor DirectivesYou can use the following
capabilities of the ESQL/C preprocessor when youdesign your
embedded code:
■ The include directive expands ESQL/C include files within
yourprogram.
■ The define and undef directives create compile-time
definitions.
■ The ifdef, ifndef, else, elif, and endif directives specify
conditionalcompilation.
As with embedded SQL statements, you can use either of two
formats forESQL/C preprocessor directives:
■ The EXEC SQL keywords:EXEC SQL preprocessor_directive;
■ The dollar sign ($) notation:$preprocessor_directive;
1-12 INFORMIX-ESQL/C Programmer’s Manual
-
The include Directive
In either of these formats, replace preprocessor_directive with
one of the validprocessor directives that the following sections
describe. You must terminatethese directives with a semicolon
(;).
Important: The EXEC SQL keywords conform to ANSI standards.
The ESQL/C preprocessor works in two stages. In Stage 1, it acts
as a prepro-cessor for the ESQL/C code. In Stage 2, it converts all
of the embedded SQLcode to C code. The ESQL/C preprocessor handles
the preprocessor directivesat different stages, as follows:
The remainder of this section describes each of the ESQL/C
preprocessordirectives in more detail.
The include DirectiveThe include directive allows you to specify
a file to include within yourESQL/C program. When it reaches an
include directive, the ESQL/C prepro-cessor places the contents of
the specified file into the ESQL/C source file.Stage 1 of the
ESQL/C preprocessor reads the contents of filename into thecurrent
file at the position of the include directive.
You can use the include preprocessor directive in either of the
following twoformats:
■ EXEC SQL include filename;
■ $include filename;
In either of these formats, replace filename with the name of
the file to beincluded in your program. You can specify filename
with or without quotationmarks around the filename. However, if you
use a full pathname, you mustenclose the pathname in quotation
marks. The following example shows howto use full pathnames on a
Windows system.
EXEC SQL include decimal.h;
EXEC SQL include "C:\apps\finances\credits.h";
If you omit the quotes around the filename, ESQL/C changes the
filename tolowercase characters. If you omit the pathname, the
ESQL/C preprocessorchecks the preprocessor search path for the
file. For more information on thissearch path, see “Naming the
Location of Include Files” on page 1-62.
Programming with INFORMIX-ESQL/C 1-13
-
The define and undef Directives
You can use include for the following types of files:
■ An ESQL/C header file
You do not have to use the .h file extension for an ESQL/C
header file;the compiler assumes that your program refers to a file
with a .hextension. The following examples show valid statements to
includeESQL/C header files:
EXEC SQL include varchar.h;$include sqlda;EXEC SQL include
sqlstype;
For a complete list of ESQL/C header files, see page 1-22.
■ Other user-defined files
You must specify the exact name of the file that you wish to
include.The compiler does not assume the .h extension when you
include aheader file that is not an ESQL/C header file.
The following examples show valid statements to include the
filesconstant_defs and typedefs.h in a UNIX environment:
EXEC SQL include constant_defs;EXEC SQL include
"/work/esqlcstuff/constant_defs";$include typedefs.h;EXEC SQL
include "/work/include/typedefs.h";
You must use the include directive if the file you specify
contains SQLstatements.
Tip: To include system header files, use the standard #include
directive of theC preprocessor. The #include of C includes a file
after ESQL/C preprocessing.
The define and undef DirectivesThe ESQL/C preprocessor allows
you to create simple variables that areavailable only to the ESQL/C
preprocessor. Informix calls these variablesdefinitions. The ESQL/C
preprocessor manages these definitions with twodirectives:
define creates a name-flag definition. The scope of this
definition is fromthe point where you define it to the end of the
ESQL/C source file.
undef removes a name flag that EXEC SQL define or $define
creates.
1-14 INFORMIX-ESQL/C Programmer’s Manual
-
The define and undef Directives
The ESQL/C preprocessor rather than the C preprocessor (which
processes#define and #undef) processes these directives. The ESQL/C
preprocessorcreates (define) or removes (undef) these definitions
in stage 1 ofpreprocessing.
The ESQL/C define directive can create definitions with the
followingformats:
■ The format for Boolean symbols isdefine symbolname;
The following examples show the two ways to define a
Booleansymbol that is called TRANS:
EXEC SQL define TRANS;$define TRANS;
■ The format for integer constants isdefine symbolname
value;
The following examples show both formats for two
integerconstants, MAXROWS (with a value of 25), and
USETRANSACTIONS(with a value of 1):
EXEC SQL define MAXROWS 25;$define MAXROWS 25;
EXEC SQL define USETRANSACTIONS 1;$define USETRANSACTIONS 1;
Unlike the C #define statement, the define directive does not
support stringconstants or macros of statements that receive values
at runtime.
You can override definitions from the esql command line with the
-ED and-EU options. For more information about these options, see
“Defining andUndefining Definitions While Preprocessing” on page
1-60.
Programming with INFORMIX-ESQL/C 1-15
-
The ifdef, ifndef, elif, else, and endif Directives
The ifdef, ifndef, elif, else, and endif DirectivesThe ESQL/C
preprocessor supports the following directives for
conditionalcompilation:
In the following example, the BEGIN WORK statement only compiles
if youhave previously defined the name USETRANSACTIONS with a
definedirective:
EXEC SQL ifdef USETRANSACTIONS;EXEC SQL begin work;EXEC SQL
endif;b
The following example uses the dollar sign ($) format to perform
the sametask:
$ifdef USETRANSACTIONS;$begin work;$endif;
The ESQL/C preprocessor does not support a general if directive;
it supportsonly the ifdef and ifndef statements that test whether a
name has beendefined with define.
The ESQL/C preprocessor processes these directives rather than
the C prepro-cessor (which processes #ifdef and #ifndef). The
ESQL/C preprocessorprocesses conditional compilation definitions in
Stage 2 of the preprocessing.
ifdef tests a name and executes subsequent statements if define
hascreated the name.
ifndef tests a name and executes subsequent statements if define
has notcreated the name.
elif begins an alternative section to an ifdef or ifndef
condition andchecks for the presence of another define.
else begins an alternative section to an ifdef or ifndef
condition.
endif closes an ifdef or ifndef condition.
1-16 INFORMIX-ESQL/C Programmer’s Manual
-
Embedding SQL Statements
Embedding SQL StatementsAn ESQL/C program can use SQL statements
to communicate with thedatabase server. The program can use both
static and dynamic SQL statements.A static SQL statement is one in
which all the components are known whenyou compile the program. A
dynamic SQL statement is one in which you donot know all the
components at compile time; the program receives all or partof the
statement at runtime. For a description of dynamic SQL, seeChapter
12, “Working with the Database Server.”
You can embed SQL statements in a C function with one of two
formats:
■ The EXEC SQL keywords:EXEC SQL SQL_statement;
Using EXEC SQL keywords is the ANSI-compliant method to embedan
SQL statement.
■ The dollar sign ($) notation:$SQL_statement;
In either of these formats, replace SQL_statement with the
complete text of avalid statement. ESQL/C statements can include
host variables in most placeswhere you can use a constant. For any
exceptions, see the syntax ofindividual statements in the Informix
Guide to SQL: Syntax.
This section describes the following topics that are related to
usingembedded SQL statements in an ESQL/C program:
■ Case sensitivity of identifiers
■ Using quotes and escape characters
■ Commenting statements
■ Host variables
■ Header files
Programming with INFORMIX-ESQL/C 1-17
-
Handling Case Sensitivity in Embedded SQL Statements
Handling Case Sensitivity in Embedded SQL StatementsFigure 1-2
describes how the ESQL/C preprocessor treats uppercase andlowercase
letters.
Figure 1-2Case Sensitivity in ESQL/C Files
ESQL/C Identifier Case Sensitive Example
Host Variable Yes ESQL/C treats the variables fname andFname as
distinct variables:
EXEC SQL BEGIN DECLARE SECTION;char fname[16], lname[16];char
Fname[16];
EXEC SQL END DECLARE SECTION;
This sample does not generate a warningfrom the
preprocessor.
SQL Keyword No Both CONNECT statements are valid ways
ofestablishing a connection to the stores7database:
EXEC SQL CONNECT TO 'stores7';orEXEC SQL connect to
'stores7';
In examples given in this manual, SQLkeywords appear as
lowercase characters.
Statement Identifiers
Cursor Names
No The following example shows the creationof statement IDs and
cursor names:
EXEC SQL prepare st from'select * from tab1';
/* duplicate */EXEC SQL prepare ST from
'insert into tab2values (1,2)';
EXEC SQL declare curname cursorfor st;
/* duplicate */EXEC SQL declare CURNAME cursor
for ST;
This code produces errors because thestatement IDs st and ST are
duplicates, as arethe cursor names curname and CURNAME.
1-18 INFORMIX-ESQL/C Programmer’s Manual
-
Using Quotes and Escape Characters
Using Quotes and Escape CharactersAn escape character indicates
to the ESQL/C preprocessor that it should printthe following
character as a literal character instead of interpreting it. You
canuse the escape character with an interpreted character to make
the compilerescape, or ignore, the interpreted meaning.
In ANSI SQL, the backslash character (\) is the escape
character. To search fordata that begins with the string \abc, the
WHERE clause must use an escapecharacter as follows:
... where col1 = '\\abc';
However, ANSI standards specify that using the backslash
character (\) toescape single (' ') or double (" ") quotation marks
is illegal. For example, thefollowing attempt to find a single
quote does not conform to ANSI standards:
... where col1 = '\'';
In nonembedded tools such as DB-Access, you can escape a quote
with eitherof the following methods:
■ You can use the same quotation mark as an escape character,
asfollows:
... where col1 = '''';
■ You can use an alternative quotation mark. For example, to
look fora double quote, you can enclose this double quote with
single quotes,as follows:
... where col1 = ' "';
However, ESQL/C uses quotation marks differently than it uses
nonem-bedded tools. Figure 1-3 shows a SELECT statement with a
WHERE clause thatcontains a double quote enclosed with single
quotes.
EXEC SQL select col1 from tab1 where col1 = ' "';Figure 1-3A
SELECT
Statement with anInvalid WHERE
Clause
Programming with INFORMIX-ESQL/C 1-19
-
Using Quotes and Escape Characters
For the WHERE clause in Figure 1-3 on page 1-19, the ESQL/C
preprocessordoes not process a double quote; it just passes it on
to the C compiler. Whenthe C compiler receives the string ' " '
(double quote enclosed with singlequotes), it interprets the first
single quote as the start of a string and thedouble quote as the
end of a string. The compiler cannot match the singlequote that
remains and therefore generates an error.
To resolve this misinterpretation, you can escape the double
quote with the Cescape character, the backslash (\). The correct
syntax for the query inFigure 1-3 is as follows:
EXEC SQL select col1 from tab1 where col1 = '\"';
Because both C and ANSI SQL use the backslash character as the
escapecharacter, be careful when you search for the literal
backslash in embeddedqueries. To search for the string "\" (where
the double quotes are part of thestring), enter five backslashes in
the following query:
EXEC SQL select col1 from tab1 where col1 = '\"\\\\\"';
Figure 1-4 shows the string after it has passed through each of
the processingsteps.
Figure 1-4Escaped Query String As It Is Processed
ESQL/C supports strings in either single quotes ('string') or
double quotes("string"). However, the C language supports strings
only in double quotes.Therefore, the ESQL/C preprocessor converts
every statement in an ESQL/Csource file into double-quoted
string.
Processor After Processing
ESQL/C preprocessor '\"\\\\\"'
C compiler '"\\"'
ANSI-compliant database server '"\"'
1-20 INFORMIX-ESQL/C Programmer’s Manual
-
Adding Comments
Adding CommentsTo add comments to an ESQL/C program, you can use
either of the followingformats:
■ You can use a double dash (--) comment indicator on any
ESQL/Cline (one that begins with either EXEC SQL or $ and
terminates witha semicolon). The comment continues to the end of
the line.
For example, the following line of code includes a
DATABASEstatement that opens the stores7 database and a comment to
thateffect:
EXEC SQL database stores7; -- stores7 database is open
now!printf("\nDatabase opened\n"); /* This is not an ESQL/C */
/* line so it needs a *//* regular C notation *//* for a comment
*/
■ You can use a standard C comment on an ESQL/C line, as shown
inthe following example:
EXEC SQL begin work; /* You can also use a C comment here */
Specifying Host VariablesHost variables are normal C variables
that you use in embedded SQL state-ments. When you use a host
variable in an SQL statement, you must precedeits name with a
symbol to distinguish it from regular C variables. You can
useeither of the following symbols:
■ A colon (:)
For example, to specify the host variable that is called hostvar
as aconnection name, use the following syntax:
EXEC SQL connect to :hostvar;
■ A dollar sign ($)
For example, to specify the host variable that is called hostvar
as aconnection name, use the following syntax:
EXEC SQL connect to $hostvar;
Important: Using the colon (:) as a host-variable prefix
conforms to ANSI SQLstandards.
Programming with INFORMIX-ESQL/C 1-21
-
Using ESQL/C Header Files
When you list more than one host variable within an SQL
statement, separatethe host variables with commas (,). For example,
the esql command inter-prets the following line as two host
variables, host1 and host2:
EXEC SQL select fname, lname into :host1, :host2 from
customer;
If you omit the comma, esql interprets the second variable as an
indicatorvariable for the first host