Check the API version of a library

When you invoke the IBM® Informix® ESQL/C application that is linked with shared HCL Informix general libraries, the release number of these shared libraries must be compatible with that of the shared libraries in the $INFORMIXDIR/lib or the %INFORMIXDIR%\lib directory.

In a Windows environment, a developer can easily verify the name of the shared library DLL, namely isqltnnx.dll, where nn stand for the version number, and x stand for the API version.

For the Informix ESQL/C application on UNIX, however, given that the linked libraries get symbolic names, it is not easy to find the version number of the linked library. Therefore, Informix ESQL/C does this check for you. Informix ESQL/C performs an internal check between the API version of the library that the application uses and the API version of the library that is installed as part of your Informix ESQL/C product. Figure 1 shows where the API version appears in the shared library name.

Informix ESQL/C uses the HCL Informix function that is called checkapi() to perform this check. The checkapi() function is in the checkapi.o object file, which is contained in the $INFORMIXDIR/lib/esql directory. The esql command automatically links this checkapi.o object file with every executable that it creates.

To determine the API version of the library that the application uses, Informix ESQL/C checks the values of special macro definitions in the executable file. When the Informix ESQL/C preprocessor processes a source file, it copies the macro definitions from the sqlhdr.h header file into the C source file (.c) that it generates. The following example shows sample values for these macros:

#define CLIENT_GEN_VER                  710
#define CLIENT_OS_VER                  710
#define CLIENT_SQLI_VER                  710
#define CLIENT_GLS_VER                  710

Tip: The Informix ESQL/C preprocessor automatically includes the sqlhdr.h file in all Informix ESQL/C executable files that it generates.

If the API version of the libraries in this executable file is not compatible, Informix ESQL/C returns a runtime error that indicates which library is not compatible. You must recompile your Informix ESQL/C application to link the new release version of the shared library.

If you do not use esql to link one of the shared Informix general libraries with your Informix ESQL/C application, you must explicitly link the checkapi.o file with your application. Otherwise, Informix ESQL/C might generate an error at link time of the form:

undefined ifx_checkAPI()