INFORMIX
Informix-ESQL/C Programmer's Manual
Chapter 1: Programming with INFORMIX-ESQL/C
Home Contents Index Master Index New Book

Compiling and Linking Options of the esql Command

 The following sections describe the compiling and linking options of the esql command.

UNIX

Syntax of the Compiling/Linking Options for UNIX

The following diagram shows the compiling and linking options that can be passed to the esql command.

ccargs

are command-line arguments that esql does not interpret but passes to the C compiler.

-lsystemlib

indicates other system libraries that you want to link, where systemlib is a string that is the abbreviated name of the library and is appended to the constant l.

-o executable name

specifies the name of the executable file.

otherCobj.o

specifies a C object file that you want to link with esqlfile.ec.

otherCsrc.c

specifies a C source file that you want to compile and link with esqlfile.ec.

-static

links Informix static libraries instead of the default Informix shared libraries.

-thread

links Informix thread-safe libraries instead of the default Informix shared libraries.

yourlib.a

specifies your own special static library that you want to link.

Naming the Executable File on UNIX

When the esql command successfully completes, it creates a C object file for your ESQL/C program. By default, the C compiler names this object file a.out. Often, you want the executable file to have the same name as the ESQL/C source file but without the .ec extension.

You can explicitly specify the name of the object file with the -o option. For example, the following esql command produces an executable file that is called custinpt (instead of a.out):

You can also create a shared object file from your source .ec file by giving standard C compiler options for shared objects. The esql command passes these options to the C compiler:

Passing Options to the C Compiler

 If you list options in the command line that the esql command does not support, it passes the options to the C compiler. For example, the following esql command in a UNIX environment passes the -c option to the C compiler because the esql command does not recognize the -c option.

For most C compilers, the -c option suppresses the loading phase of compilation and forces creation of an object file, even if you compile only one program.

Specifying a Particular C Compiler

The INFORMIXC environment variable lets you specify the name or pathname of the C compiler that the esql command uses to generate compiled files. If you do not set INFORMIXC, the default compiler is cc. For a full description of this environment variable, refer to the Informix Guide to SQL: Reference.

WIN NT/95

Syntax of the Compiling/Linking Options for Windows Environments

The following diagram shows the syntax of the esql processor options available when you want to only preprocess and compile an ESQL/C program but do not want to link it.

The following diagram shows the syntax of the esql processor options that are available in a Windows environment when you want to preprocess, compile, and link an ESQL/C program.

-c

preprocesses and compiles but does not link.

-bc

invokes the Borland C compiler.

-cc

indicates that you want to pass a C compiler option that has the same name as an ESQL/C processor option. This option tells the ESQL/C processor not to interpret the next option.

ccargs

are command-line arguments that esql does not interpret but passes to the C compiler.

cfile.c

indicates C source file(s) that you want to compile and link.

deffile.def

indicates a module-definition file that you want to link.

-l linkargs

marks the end of the compiler arguments and the start of linker arguments.

-mc

invokes the Microsoft C compiler, which is the default C compiler.

objfile.obj

indicates other C object file(s) that you want to link.

-r rcargs

marks the end of the linker arguments (or the end of the compiler arguments, if no linker arguments are specified) and the start of resource compiler arguments.

resfile.rc

specifies your own resource file containing resource script statements that you want to send to the resource compiler. The resource compiler compiles the .rc file into an .res file, which is linked into the target ESQL/C program.

resfile.res

specifies your own compiled resource files that you want linked.

syslibfile

indicates other system libraries that you want linked.

yourlib.lib

specifies your own special library that you want linked.

Naming the Executable File in Windows Environments

When esql successfully completes, it creates a target ESQL/C program. For the ESQL/C program, this target can be either an executable file (.exe) or a DLL file (.dll). (The -target command-line option determines whether esql creates an executable or DLL file. For more information, see "Syntax of the Options for Windows Environments".)

By default, the name of this target file is the name of the first ESQL/C source file on the esql command line. Often, you want the executable file to have a name that clearly identifies the purpose of the executable program.

You can explicitly specify the name of the executable file with the -o option. For example, the following esql command produces an executable file called inpt (instead of custinpt.exe):

Passing Options to the C Compiler in Windows Environments

 The esql command processor passes any unrecognized arguments in the command line to the C compiler. For example, because esql does not recognize -Zi as an option, the following esql command passes the -Zi option to the C compiler:

If you want to pass a C compiler option that has the same name as an ESQL/C processor option, precede the C compiler option with the -cc option. For example, the following esql command passes the -od option to the C compiler, suppressing interpretation of the option by the ESQL/C processor:

Specifying a Particular C Compiler in Windows Environments

 ESQL/C in Windows environments supports the following C compilers:

Either the Microsoft C compiler or the Borland C compiler must reside on your computer before you can compile an ESQL/C program. The default C compiler option, -mc, invokes the Microsoft compiler. To choose the Borland compiler, use the -bc option.

Compiling Without Linking

By default, the ESQL/C command processor preprocesses, compiles, and links the ESQL/C program and creates either an executable file or a DLL. To suppress the linking of your ESQL/C program specify the -c option. With this option, esql only preprocesses and compiles the code. The output of this command is a C object file (.obj extension) for each C source file (.c) or ESQL/C source file (.ec).

For example, to preprocess and compile the ESQL/C source file demo1.ec, use the following command:

The preceding command generates a C object file called demo1.obj. The following esql command preprocesses demo1.ec, checks for Informix extensions to X/Open-standard syntax, and suppresses warning messages:

Important: If you specify the conflicting options -c and -o, the preprocessor ignores the -o option and processes the -c option. The preprocessor reports the conflict in an error message.
WIN NT/95

Special Compile Options for Windows Environments

 You can give the following additional compile options to the esql command if you are running ESQL/C in a Windows environments.

Using a Project File

The -f option enables you to specify the name of a project file at the esql command line. The filename that follows -f is a project file that contains the names of the ESQL/C source (.ec) files to compile.

For example, suppose the project file, project.txt, contains the following lines:

In this example, first.ec, second.ec, and third.ec represent the names of ESQL/C source files that you want to compile.

The following esql command uses the project.txt project file to specify the three source files to compile and link:

The preceding esql command is the equivalent of the following esql command:

You can accomplish the same task with a response file. For more information about response files, see "Creating a Response File".

Creating a Response File

You can specify the command-line arguments for the ESQL/C command processor in a response file and specify the filename for the ESQL/C processor. The ESQL/C response file is a text file with ESQL/C command-line options and filenames, separated by a space, a new line, a carriage return, a line feed, or a combination of these characters.

The following example shows the syntax that specifies a response file called resp.esq:

The response file, resp.esq, might contain the following lines:

Use of this response file is the equivalent of the following esql command:

In this example, project.txt is a project file that contains the filenames first.ec, second.ec, and third.ec on separate lines, as the previous shows.

You might use a response file for the following reasons:

Implicit Options Invoked by the esql Preprocessor in Windows Environments

 The ESQL/C command processor implicitly passes compiler and linker flags to the supported C compilers. Figure 1-25 lists the implicit options that esql passes when you use the indicated esql options. If you choose to create your own build file, use the indicated flags as appropriate for your application.

Important: The esql command does not implicitly pass any options to the resource compiler.

Figure 1-25
Implicitly Passed Compiler Options

Compiler Module Type esql Options Implicit Options
Compiler Linker

Microsoft
Visual
C++,
Version
2.x or
later

executable

-target:exe
-we

-c -I%INFORMIXDIR%\incl\esql
/D_systype /D_proctype
/threadtype /DWIN32

-DEF:deffile -OUT:target -MAP
-SUBSYSTEM:systype
%INFORMIXDIR%\lib\isqlt09a.lib
%INFORMIXDIR%\lib\igl4g303.lib
%INFORMIXDIR%\lib\iglxg303.lib
%INFORMIXDIR%\lib\igo4g303.lib
libset

dll

-target:dll
-wd

-c -I%INFORMIXDIR%\incl\esql
/D_systype /D_proctype
/threadtype /DWIN32

-DLL -DEF:deffile -OUT:target -MAP
-SUBSYSTEM:systype
%INFORMIXDIR%\lib\isqlt09a.lib
%INFORMIXDIR%\lib\igl4g303.lib
%INFORMIXDIR%\lib\iglxg303.lib
%INFORMIXDIR%\lib\igo4g303.lib
libset

Borland C++,
Version 5

executable

-target:exe
-we

-c -I%INFORMIXDIR%\incl\esql
-etarget -subtype
-libtlog -libtlg

-c -Tpe -M
-DEF:deffile -subsystem
%INFORMIXDIR%\lib\isqlb09a.lib
%INFORMIXDIR%\lib\igl4b303.lib
%INFORMIXDIR%\lib\iglxb303.lib
%INFORMIXDIR%\lib\igo4b303.lib
c0t32.obj
libset

dll

-target:dll
-wd

-c -I%INFORMIXDIR%\incl\esql
-etarget -subtype
-libtlog -libtlg

-c -Tpd -M
-DEF:deffile -subsystem
%INFORMIXDIR%\lib\isqlb09a.lib
%INFORMIXDIR%\lib\igl4b303.lib
%INFORMIXDIR%\lib\iglxb303.lib
%INFORMIXDIR%\lib\igo4b303.lib
c0d32.obj
libset

The italicized terms in the compiler and linker options represent the following definitions.

Term Definition

deffile

name of a .def file. (The -DEF option executes only if you specify a .def file on the command line.)

libset

library set (depends on whether the application is WINDOWS or CONSOLE).

libtlg

-D_RTLDLL for a dynamic library or " " for a shared library.

libtlog

-WM for a multithread library or " " for a single-thread library.

proctype

type of processor (X86).

subsystem

ap for a console subsystem or aa for a Windows subsystem.

subtype

WC for a console executable, W for a Windows executable file, WCD for a console DLL, or WD for a Windows DLL.

systype

type of subsystem (WINDOWS or CONSOLE).

t

X for a console subsystem and W for a Windows subsystem.

target

name of the executable file (name of first .ec file or the name specified by the -o command line option).

threadtype

type of thread option (ML, MT, MD, depending on the value of the -runtime command-line option).

For more information on the -target, -wd, and -we command-line options, see page 1-91.

Important: As the Linker column of the table in Figure 1-25 indicates, the library file in the %INFORMIXDIR%\lib directory is isqlt09a.lib.
The library set that the linker uses depends on whether you are creating a Windows or console application. Figure 1-26 lists the library sets that the indicated esql options use.

Figure 1-26
Library Sets That the Linker Uses

Compiler esql Options Library Sets That the Linker Uses

Microsoft Visual C++, Version 2.x or later

-subsystem:windows
-Sw
-ss:w

advapi32.lib
wsock32.lib
user32.lib
winmm.lib
gdi32.lib
comdlg32.lib
winspool.lib

-subsystem:console
-Sc
-ss:c

netapi32.lib
wsock32.lib
user32.lib
winmm.lib

Borland C++,
Version 5

-subsystem:windows
-Sw
-ss:w

cw32mti.lib
import32.lib

-subsystem:console
-Sc
-ss:c

cw32mti.lib
import32.lib

General Options That Affect Linking

The C compiler performs the linking phase of an ESQL/C compile. This section describes the esql command-line arguments that affect how this linking occurs.

Linking Other C Source and Object Files

You can list the following types of files on the esql command line to indicate that you want the link editor to link to the resulting object file:

    If you list files with the .c extensions, esql passes them through to the C compiler, which compiles them to object files (.o extensions) and links these object files.

    If you list files with .o or .obj extensions, esql passes them through to the C compiler, which links these object files.The link editor links the C object files with the appropriate ESQL/C library functions.

Tip: If you specify uncompiled resource files, esql passes them to the resource compiler and links the resulting .res file to the ESQL/C application.
The ESQL/C command preprocessor passes these files directly to the linker. It also links the libraries it needs to support the ESQL/C function library. You can use the -libs option to determine which libraries esql automatically links, as follows:

Specifying Versions of Informix General Libraries

 By default, the esql command links the shared libraries for the Informix general libraries: libgen, libos, libgls, libafs, and libsql. To use shared libraries, your computer must support shared memory.

You can use the following command-line options to change which versions of the Informix general libraries the preprocessor links with your program:

You can combine these options to tell the preprocessor to link in the thread-safe versions of the Informix static libraries. For more information on this topic, see "The esql Command".

WIN NT/95

Special Linking Options for Windows Environments

The following sections give linking options that can only be used in Windows environments.

Passing Arguments to the Linker

On the esql command line, you can list linker arguments by prefacing them with the -l processor option. The esql command processor passes to the linker all arguments after the -l option, up to whichever of the following items it encounters first:

Passing Arguments to the Resource Compiler

 On the esql command line, you can list resource compiler arguments by prefacing them with the -r processor option. The ESQL/C command processor passes to the resource compiler all arguments after the -r, up to the end of the command line. The processor then runs the resource compiler to create a .res file, which it then passes to the linker. If you specify the -r option but do not specify an associated resfile.rc, esql uses the name for the target and appends the .rc extension.

ESQL/C Dynamic Link Libraries

For Windows environments, the ESQL/C product includes the following dynamic link libraries (DLLs):

Informix DLLs are located in the %INFORMIXDIR%\bin directory. %INFORMIXDIR% is the value of the INFORMIXDIR environment variable.

Using the Same Runtime Routines for Version Independence

If your application was compiled with a version of Microsoft Visual C++ earlier than 4.x, you need to export your C runtime library to the ESQL client-interface DLL (isqlt09a.dll). The ESQL client-interface DLL uses your runtime routines to make sure all the pieces of your application are compiled with the same runtime version. Any application that is linked to your application and calls ESQL/C library routines or SQL statements must also use your C runtime library.

To export a C runtime library, include the following line in your code before the first call to an ESQL/C library routine or SQL statement:

The infxcexp.c file contains the C code to export the addresses of all C runtime routines that the ESQL client-interface DLL uses. This file is in the %INFORMIXDIR%\incl\esql directory, which the esql command processor automatically searches when it compiles a program. If you do not use the esql command processor, add the %INFORMIXDIR%\incl\esql directory to the compiler search path before you compile.

You need to include the infxcexp.c file only once, in the main() routine (once per process), before the first ESQL/C library call or SQL statement in the program. The code in this file exports your runtime library to the ESQL runtime DLL (isqlt09a.dll) so that they use the same C runtime code. Exporting your runtime routines enables the ESQL runtime routines to allocate memory (malloc()), return the pointer to a C program, and let the program free the memory (free()). It also enables a C program to open a file and to pass the handle (or file pointer) to the ESQL runtime routines for read-write access.

WIN NT/95

Windows Operating System Processor Options Available to the esql Command

The options that the esql command processor supports for Windows environments enable you to control the following features of your ESQL/C program:

This section describes the syntax of the esql processor options for Windows environments.

Syntax of the Options for Windows Environments

Figure 1-27 shows the syntax of the processor options that are available when you use esql either to preprocess and compile only (-c command-line option) or to preprocess, compile, and link an ESQL/C program.

Figure 1-27
Windows Environment Options available to esql

-cpu:

indicates that the target ESQL/C program is to run on the central processing unit (CPU) that cpuname specifies. The Borland C compiler supports only Intel 386 CPUs, so it generates the code for a 386 CPU regardless of the cpu variable.

-cpu:i

indicates that the CPU type for the target ESQL/C program is Intel 386 (same as -cpu:i386 and -Pi). This option specifies the default CPU type that esql uses. Informix maintains this option for backward compatibility.

cpuname

specifies the name of the type of CPU to use for the target ESQL/C program. Valid value is i386, for an Intel 386 CPU. The default CPU type that esql uses is i386.

-Pi

indicates that CPU type is an Intel 386 (same as -cpu:i and -cpu:i386). This option is case sensitive. ESQL/C supports this option for compatibility with INFORMIX-ESQL/C for Windows NT, Version 5.01. This option specifies the default CPU type that esql uses.

rlibname

specifies the name of the C runtime library to link into the target ESQL/C program. Valid values are libc, libcmt, and msvcrt. The default C runtime library that esql links is msvcrt.

-rt:d

indicates that the target ESQL/C program is to include the multithreaded C msvcrt runtime DLL (same as -runtime:msvcrt). If you do not choose -rt:d, -rt:m, or -rt:s, esql assumes -rt:d, which is the default value for the -rt option. (For Borland C, the runtime DLL is -runtime:cw32mti.)

-rt:m

indicates that the target ESQL/C program is to include the static, multithreaded C libcmt runtime library (same as -runtime:libcmt). (For Borland C, the runtime DLL is -runtime:cw32mt.)

-rt:s

indicates that the target ESQL/C program is to include the static, single-threaded C libc runtime library (same as -runtime:libc). If you do not choose -rt:d, -rt:m, or -rt:s, esql assumes -rt:d. (For Borland C, the runtime DLL is -runtime:cw32.)

-rt:t

indicates that the target ESQL/C program is to include the single-threaded C CW32i runtime DLL (same as -runtime:cw32i). This option is for the Borland C compiler only.

-runtime:

indicates that the esql processor is to link the runtime library that rlibname specifies into the target ESQL/C program.

-ss:c

creates a console-based application for the target ESQL/C program (same as -Sc and -subsystem:console). If you do not choose -ss:c or -ss:w, esql assumes -ss:w.

-ss:w

creates a Windows-based application for the target ESQL/C program (same as -subsystem:windows and -Sw). This option specifies the default subsystem type that esql uses.

-subsystem:
console

creates a console-based application for the target ESQL/C program (same as -Sc and -ss:c). If you do not choose -subsystem:console or -subsystem:windows, esql assumes -subsystem:windows.

-subsystem:
windows

creates a Windows-based application for the target ESQL/C program (same as -ss:w and -Sw). This option specifies the default subsystem-type that esql uses.

-Sc

creates a console-based application for the target ESQL/C program (same as -ss:c and -subsystem:console). If you do not choose -Sc or -Sw, esql assumes -Sw. This option is case sensitive. ESQL/C supports this option for compatibility with INFORMIX-ESQL/C for Windows NT, Version 5.01.

-Sw

creates a Windows-based application for the target ESQL/C program (same as -subsystem:windows and -ss:w). This option specifies the default subsystem type that esql uses. This option is case sensitive. ESQL/C supports this option for compatibility with INFORMIX-ESQL/C for Windows NT, Version 5.01.

-target:dll

creates a Windows DLL (.dll) for the target ESQL/C program (same as -wd). If you do not choose -target:exe or -target:dll, esql assumes -target:exe.

-target:exe

creates a Windows executable file (.exe) for the target ESQL/C program (same as -we). This option specifies the default target type that esql uses.

-wd

creates a Windows DLL (.dll) (same as -target:dll). If you do not choose -we or -wd, esql assumes -we.

-we

creates a Windows executable file (.exe) (same as -target:exe). This option specifies the default target type that esql uses.

WIN NT/95

Accessing the ESQL Client-Interface DLL in Windows Environments

A DLL is a collection of functions and resources that can be shared by applications. It is similar to a runtime library in that it stores functions that many applications need. It differs, however, from a runtime library in the way that it is linked to the calling application.

Libraries that are linked at compile time are static-link libraries. The libraries such as libc and libcmt (used with the Microsoft Visual C++, Version 2.x) are static-link libraries. Whenever you link one of these Microsoft Visual C++ (Version 2.x) libraries to your application, the linker copies the code from the appropriate static-link library to the executable file (.exe) for your application. By contrast, when you link dynamically, no code is copied to the executable file of your application. Instead, your functions are linked at runtime.

Static-link libraries are effective in an environment where no multitasking is required. However, they become inefficient when more than one application calls the same functions. For example, if two applications that are running simultaneously in a Windows environment call the same static-link function, two copies of the function reside in memory. This situation is inefficient.

But if a function is dynamically linked, Windows NT and Windows 95 first checks memory to see if a copy of the function already resides there. If a copy exists, the Windows system uses that copy rather than making another copy. If the function does not yet exist in memory, the Windows system links or copies the function into memory from the DLL.

The ESQL/C library functions, as well as other internal functions, are contained in the ESQL client-interface DLL. To use these functions in your ESQL/C application, you must perform the following tasks:

Accessing the Import Library

 To enable your ESQL/C application to access the ESQL client-interface DLL, Informix provides the import library of the DLL. The linker uses an import library to locate functions that are contained in the DLL. It contains references that reconcile function names used in an application with the library module that contains the function.

When you link a static library to your application, the linker copies program code from your static-link libraries to the executable file. However, if you link an import library to your application, the linker does not copy the program code when it links the executable file. Instead, the linker stores the information needed to locate the functions in the DLL. When you run your application, this location information serves as a dynamic link to the DLL.

The ESQL client-interface library provides location information for the ESQL/C function calls. The esql command processor automatically links the import and Windows libraries for the DLL whenever you use it to compile and link your ESQL/C program.

Locating a DLL

During the development of your application, the ESQL/C software (such as the esql command processor) must be able to access object libraries and import libraries. However, DLLs must be accessible when the application is running. Consequently, Windows must be able to locate them on your hard disk.

Windows NT and Windows 95 search directories for your DLL in the following order:

    1. The directory from which you loaded the application

    2. The current directory (where the executable file exists or the working directory that the Program Item Properties value for the icon specifies)

WIN NT
    For Windows NT, the 32-bit Windows environment directory, SYSTEM32. (To get the path of this directory, use the GetSystemDirectory() function.)

WIN 95

    WIN NT
    3. For Windows NT only, the 16-bit Windows environment system directory, SYSTEM

    4. The Windows directory

    To get the path of this directory, use the GetWindowsDirectory() function.

    5. Directories that your PATH environment variable lists

Building an Application DLL

 You can tell the ESQL/C processor to build an ESQL/C program as a DLL (.dll file) with the -target (or -wd) command-line option. Such an ESQL/C program is called an application DLL.

To build an ESQL/C program as a DLL, follow the guidelines for general-purpose DLLs. For more information, refer to your system documentation. Compile the ESQL/C source file with the -target:dll (or -wd) to create the application DLL.

For an example of how to build an application DLL, see the WDEMO demo program in the %INFORMIXDIR%\demo\wdemo directory. The ESQL/C source file for the sample application DLL is called wdll.ec. To compile this DLL, use the following esql command:

The source code for the WDEMO executable file is in the wdemo.exe file.



Informix-ESQL/C Programmer's Manual, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.