Using INFORMIX-GLS
To use INFORMIX-GLS in a C-language program, include the following header file in the source file:
Figure 1-1 lists the directory in which this header file is located.
This section provides the following additional information about how to use the INFORMIX-GLS library:
For more information about a particular INFORMIX-GLS function, see Chapter 4, "INFORMIX-GLS Function Descriptions."
Compiling and Linking INFORMIX-GLS
The following table lists the directories that must be accessible to compile and link an ESQL/C or DataBlade program with INFORMIX-GLS.
These directories all assume that the INFORMIXDIR environment variable is set to the directory where your Informix products are installed.
INFORMIX-GLS in ESQL/C Applications
To compile and link ESQL/C applications that use INFORMIX-GLS, issue the following command:
The esql preprocessor automatically links the INFORMIX-GLS library into an ESQL/C application. It also links in the version of the GLS libraries (shared or static) that you specify with command-line options. For more information on how to compile an ESQL/C application, see the INFORMIX-ESQL/C Programmer's Manual. 
INFORMIX-GLS in DataBlade Programs
The way to compile and link a DataBlade program depends on whether the program is:
DataBlade Client Applications
This section provides information for how to compile and link a DataBlade client application with the INFORMIX-GLS libraries. For information on how to write and compile DataBlade client applications, see the DataBlade API Programmer's Manual.
Both Windows NT and UNIX require that you specify the location of the INFORMIX-GLS header file, ifxgls.h. This header file is located in the following directory:
This directory also contains many of the other files that a DataBlade client application uses. Therefore, it is an important directory to include when you compile the application.
The following command uses the Microsoft compiler, cl, to compile a DataBlade client application called sample.c that uses INFORMIX-GLS:
All INFORMIX-GLS functions are exported throughthe LIBTHDMI.LIB library. For linking, you must specify the following two libraries.
Make sure to include the $INFORMIXDIR/incl/public directory with the -I compiler, as follows:
The preceding command assumes that the API client libraries have been installed the directory that the INFORMIXDIR environment variable indicates.
On UNIX platforms, you must explicitly specify the location and name of this library, as follows:
The following command links the sample.o object file to create an executable file called sample:
Alternatively, you can use the ESQL/C preprocessor, esql, to compile and link the DataBlade client application. The esql preprocessor automatically links in most of the libraries that the client application requires (including the INFORMIX-GLS library). However, you must explicitly specify the libdmi library. The following esql command compiles and links the sample.o object file:
DataBlade UDRs
This section provides information for how to compile and link a DataBlade UDR. For more information on how to write user-defined routines, see Extending INFORMIX-Universal Server: User-Defined Routines, the DataBlade API Programmer's Manual, and the DataBlade Developers Kit documentation.
The GLS libraries are already linked to the database server. All INFORMIX-GLS functions are exported through the SAPI.LIB library. Therefore, you do not need to specify the INFORMIX-GLS library explicitly when you compile and link a DataBlade UDR on Windows NT.
The following sample commands compile and link a DataBlade UDR called func1() that uses the INFORMIX-GLS library:
The preceding commands assume that the Informix software is installed on the d: drive in a directory called informix. The resulting dynamic link libraries (DLLs) must have the READONLY attribute set to be executable. Set the READONLY flag with the attrib +r command.
The Microsoft compiler, cl, defaults to the /MT option, which specifies the multithreaded library for DLL builds. This multithreaded library is statically linked to the DLL. You can specify the /MD option to put MSVCRT40.DLL in a command path. All the UDRs that are built with /MD use one copy of the LIBC DLL. This option prevents virtual memory buildup in the database server when many UDRs are loaded.
The following sample command line shows the use of the /MD option to compile the func1() DataBlade UDR:
If MSVCRT40.DLL is not visible to the database server, the database server puts the following error in the online.log file when it attempts to execute the UDR:
On UNIX platforms, the GLS libraries are not linked to the database server. Therefore, you must explicitly specify the location and name of the INFORMIX-GLS library, as you do for DataBlade client applications. For more information, see "DataBlade Client Applications".
The location of the INFORMIX-GLS header file, ifxgls.h, is the following directory:
This directory contains many of the other files that a DataBlade client application uses. Make sure that you include this directory with the -I option of the compiler.
Additionally, you need to indicate that the DataBlade module is a DataBlade UDR (which runs on the server computer), not a DataBlade client application (which runs on a client computer). Include the following compiler flag when you compile a DataBlade UDR:
The following sample compilation and link builds a shared object called udrs.so that contains the C code for a DataBlade UDR called func1():
Initializing the INFORMIX-GLS Library
Before you can use INFORMIX-GLS functions in your application, these functions must be able to access the current processing locale. The ifx_gl_init() function initializes the current processing locale to the client locale. It creates a global locale structure that the INFORMIX-GLS functions can access to obtain the name of the current processing locale.
Whether an application requires a call to the ifx_gl_init() function depends upon whether the application establishes its own connection to a database server or executes in the context of an existing database server connection:
The database server uses a server-processing locale to obtain locale information for its own internal sessions and for any connections. It uses the values of the client locale, database locale, and server locale, as well as other environment information to determine the server-processing locale. DataBlade UDRs are not required to call the ifx_gl_init() function. For more information on the server-processing locale and how the database server establishes it, see the Informix Guide to GLS Functionality.
The ifx_gl_init() function does not generate an error if you call it multiple times within the same application. The first time that the application calls ifx_gl_init(), the function initializes the global locale structure. Subsequent calls do not result in multiple locale structures.
Handling INFORMIX-GLS Exceptions
Many of the INFORMIX-GLS functions return a unique value if they encounter an error. To further identify the cause of the error, you can use the ifx_gl_lc_errno() function to obtain the value of the INFORMIX-GLS fserror number. The ifx_gl_lc_errno() function returns the value of the error number as an int value. INFORMIX-GLS library functions can use ifx_gl_lc_errno() to obtain more information about an error that has occurred. The INFORMIX-GLS functions set the error number only if an error occurs, unless a particular function is documented otherwise.
To check for errors, an application usually inspects the return value of the function. If the return value is a unique value to indicate that an error occurred, the application can check for the error number with ifx_gl_lc_errno(). Because any INFORMIX-GLS library function can set the error number, you must call ifx_gl_lc_errno() immediately after the INFORMIX-GLS function in which the error occurred to inspect the relevant value of the error number.
For example, the ifx_gl_mbslen() function returns a value of -1 when it encounters an error. The following code fragment shows how to use the ifx_gl_lc_errno() function to obtain the error number:
An application can also ignore the return value of an INFORMIX-GLS function and just check ifx_gl_lc_errno() as long as the application sets ifx_gl_lc_errno() to zero before it calls the function:
If an INFORMIX-GLS library function does not return a unique value to indicate that an error has occurred, you must use the preceding technique to obtain the error number. For example, the following code fragment tests whether the ifx_gl_ismupper() function has detected an illegal multibyte character:
You can set ifx_gl_lc_errno() to zero and check it after a function call only if the current processing locale was initialized correctly with ifx_gl_init(). For example, the following code fragment of a client application results in a memory fault because the current processing locale is uninitialized:
In the preceding code fragment, the ifx_gl_lc_errno() function can write or read the error number only after a call to the ifx_gl_init() function has correctly initialized the current processing locale.
The preceding code fragment would work in a DataBlade UDR because a DataBlade UDR does not need to call ifx_gl_init() to initialize the current processing locale.
The following code fragment of a client application executes successfully because it correctly initializes the server-processing locale:
For multithreaded ESQL/C applications, the error-number value is stored as a field in the thread control block. Therefore, multithreaded ESQL/C applications can use the error number.
Allocating Memory
If an INFORMIX-GLS function allocates memory, this memory is only allocated within the function itself and is freed before the function returns. No INFORMIX-GLS library function allocates memory that remains after the function returns. Therefore, you must allocate any memory for data that an INFORMIX-GLS function needs or returns.
DataBlade UDRs can assume that the INFORMIX-GLS functions allocate memory with a PER_ROUTINE memory duration.
You must ensure that memory is allocated for any return value or argument that a INFORMIX-GLS function provides to the calling program.
Using Stream Input and Output
Character data that contains Asian characters must be correctly processed in all graphical user interface I/O, clipboard I/O, character terminal I/O, file I/O and network I/O. The following INFORMIX-GLS functions process input and output multibyte character streams:
This function calls a function that you define to obtain the bytes that form one multibyte character from a specified location.
This function calls a function that you define to put the bytes that form one multibyte character in a specified location.
Running the Program
A client application (ESQL/C or DataBlade) that uses the INFORMIX-GLS library must be able to access the following directories at runtime.
A DataBlade UDR executes in the context of the SQL statement that called it. The calling program must have access to the preceding directories.
|
