INFORMIX-ESQL/C Programmer's Manual Compiling Programs

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

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

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):

esql -o custinpt custinpt.ec

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:

esql -G -o lesqlfile.so esqlfile.ec

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 on UNIX passes the -c option to the C compiler because the esql command does not recognize the -c option.

esql -c demo1.ec

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.

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, ../sqlr/intro.htmler to the Informix Guide to SQL: Reference.

The following diagram shows the syntax of the esql processor options available when you only want to 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.

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 Additional Options for Windows.)

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):

esql -o inpt custinpt.ec ordinpt.ec

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:

esql -Zi demo1.ec

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:

esql -cc -od demo1.ec

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

• Microsoft Visual C++, Version 2.x or later
• Borland C++, Version 5

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.

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:

esql -c demo1.ec

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:

esql -c -xopen -nowarn demo1.ec


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.

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

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:

first.ec

second.ec

third.ec

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:

esql -f project.txt

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

esql first.ec second.ec third.ec

You can accomplish the same task with a response file. For more information about response files, see 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:

esql @resp.esq

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

-we

first.ec

second.ec

third.ec

-r foo.rc

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

esql -we -f project.txt -r foo.rc

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:

• The command line is limited to 1,024 characters. If your esql options exceed this length, you must use a response file.
• If you use one or more sets of esql options regularly, you can save yourself a great deal of typing by putting each set in a different response file. Instead of typing the options, you can list the appropriate response file in the esql command.

The ESQL/C command processor implicitly passes compiler and linker flags to the supported C compilers. Figure 2-7 on page 2-45 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 2-7
Implicitly Passed Compiler Options

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

For more information on the -target, -wd, and -we command-line options, see Figure 2-9 on page 2-48.

The library set that the linker uses depends on whether you are creating a Windows or console application. Figure 2-8 lists the library sets that the indicated esql options use.

Syntax of Additional Options for Windows

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

• Whether to create an executable file (.exe) or a DLL (.dll) for the target ESQL/C application
• Whether to create an ESQL/C application that runs in the Windows environments or on a console subsystem
• Ability to specify which runtime libraries to link into the target ESQL/C application

Figure 2-9 shows the syntax of the additional esql preprocessor options that are available to compile and link an ESQL/C program.

Figure 2-9 Additional Options for Windows

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.

The following linking options affect both UNIX and Windows environments:

• Linking other C source and object files
• Specifying versions of Informix general libraries

The following sections describes how to specify these options.

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:

• C source files in the form otherCsrc.c

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.

• C object files in the form otherCobj.o on a UNIX operating system or otherCobj.obj in a Windows environment

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.

• Library files, either your own libraries or system libraries that are compatible with the linker
• Module definitions (.def)
• Resource files, either compiled (.res) or uncompiled (.rc)

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:

esql -libs

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:

• The -thread option tells the preprocessor to link the thread-safe versions of the Informix shared libraries.
• The -static option tells the preprocessor to link the static libraries for the Informix general libraries in a UNIX environment. If you use the -static option, you cannot set the IFX_LONGID environment variable. You need to recompile with libos.a.

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.

The following sections give linking options that you can only use in Windows environments.

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:

• The -r option to specify resource compiler options
• The end of the command line

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.

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

• The ESQL client-interface DLL (isqlt09a.dll) contains the ESQL/C library functions that the ESQL/C preprocessor needs to translate embedded SQL statements and other internal functions that are needed at runtime. For more information see Accessing the ESQL Client-Interface DLL in Windows Environments.
• The esqlauth.dll DLL provides runtime verification of the connection information that the client application sends to the database server. When your application requests a connection, ESQL/C calls the sqlauth() function, which esqlauth.dll defines. For more information on sqlauth(), see Connection Authentication Functionality in a Windows Environment.
• The Registry DLL, iregt07b.dll, is used by the Setnet32 utility and the INFORMIX-Connect library to set and access configuration information in the Registry.
• The igl4b304 .dll, igo4g303.dll, and iglxg303.dll DLLs are required for Global Language Support (GLS). For more information about code-set conversion, see the Informix Guide to GLS Functionality.

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

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:

#include "infxcexp.c";

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.