INFORMIX-ESQL/C Programmer's Manual, Version 9 · INFORMIX-ESQL/C Programmer’s Manual INFORMIX-OnLine Dynamic Server, Version 7.2x INFORMIX-OnLine Workgroup Server, Version 7.2x

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


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


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


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


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


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


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


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.


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)


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


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


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


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


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


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


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. ♦


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.


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.


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


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;


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.


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.


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.


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.


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


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.


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


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 '"\"'


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.


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

Documents

INFORMIX-ESQL/C Programmer's Manual, Version 9 · INFORMIX-ESQL/C Programmer’s Manual INFORMIX-OnLine Dynamic Server, Version 7.2x INFORMIX-OnLine Workgroup Server, Version 7.2x