GLS API for DataBlade and ESQL/C Developers

INFORMIX-Universal Server provides a Global Language Support Application Programmer's Interface (GLS API) enabling you to develop internationalized applications with a C-based interface. The GLS API relies on GLS locales which determine how an internationalized application behaves.

The GLS API provides the following ...

Data Types

Macros

Input/Output Functions

Character Classification

Character Case Conversion

Character/String Comparison

Code Set Conversion

Built-in Data Type Conversion

String Processing

Multi-byte/Wide-character Conversion

Multi-byte Memory Allocation

Multi-byte String Traversal and Indexing

Initialization and Error Handling

How to use the GLS API

You can use the GLS API either on the client or the server. All functions access the current processing locale. The current processing locale, based on the GLS environment variables and data stored in the database, must be established on both the server and client before any locale sensitive processing occurs. The server establishes the locale when a database is opened (or when a session corresponding to a client connection is established). A client-side application needs to explicitly set the processing locale with a function call.

Compiling and linking the GLS API

To use the GLS API, you must include the following code in your GLS API based programs:

#include <ifxgls.h>

ESQL/C users need to ensure that the correct processing locale is established by calling ifx_gl_init() prior to calling ifx_gl_*() functions. To compile and link ESQL/C programs that use the GLS API, issue the following ESQL command:

% esql <source_file>

Client-side users of DataBlade module API also need to ensure that the correct processing locale is established by calling ifx_gl_init() prior to calling ifx_gl_*() functions. To compile and link DataBlade module programs:

% cc -I$INFORMIXDIR/incl/esql -L$INFORMIXDIR/lib/esql ... -lixgls ... <source_file>

Additionally, DataBlade module programmers need to distinguish whether a DataBlade module runs on the server or on a client when they compile user- defined routines. To make this distinction, use the compiler flag -DMI_SERVBUILD when compiling user-defined routines.

Tip: When you use the Database Developer's Kit (DBDK) to compile user- defined routines you do not have to explicitly specify the location of the header files.

To build a shared object that contains the C code for a user-defined routine, use the following example:

% cc -I$INFORMIXDIR/incl/esql -KPIC -DMI_SERVBUILD -c <source_file>

% ld -G -o <shared object name>.so <source_file>.o

**Data Types**
type	description
gl_wchar_t	The type that holds a single 4-byte wide-character.
gl_mchar_t	An integral type that holds a single byte which is part of a multibyte character; given that a multi-byte character is composed of one or more gl_mchar_t's, it makes no sense to define or refer to a variable as an gl_mchar_t. Instead always use the type (gl_mchar_t *) when,(1) defining or referring to a single multi- byte character, and (2) when defining or referring to a string of multi-byte characters.

**Macros**
name	description
IFX_GL_IS_CODESET_ORDER	Determines whether the current locale's collation order is simply the code set order.
IFX_GL_IS_SINGLE_BYTE	Determines whether cs is a single-byte code set.
IFX_GL_MB_MAX	Returns the maximum number of bytes needed to store a multi-byte character.
IFX_GL_NO_LIMIT	Used to determine character termination.
IFX_GL_NULL	Used to signify that a string is null-terminated.
IFX_GL_PROC_CS	Returns the current locale's code set.

**Input/Output**
function	description
ifx_gl_getmb	Composes a multi-byte character from a stream.
ifx_gl_putmb	Decomposes a multi-byte character to a stream.

**Character Classification**
function	description
ifx_gl_ismalnum ifx_gl_ismalpha ifx_gl_ismblank ifx_gl_ismcntrl ifx_gl_ismdigit ifx_gl_ismgraph ifx_gl_ismlower ifx_gl_ismprint ifx_gl_ismpunct ifx_gl_ismspace ifx_gl_ismupper ifx_gl_ismxdigit	Test the multi-byte character for the respective character classification.
ifx_gl_iswalnum ifx_gl_iswalpha ifx_gl_iswblank ifx_gl_iswcntrl ifx_gl_iswdigit ifx_gl_iswgraph ifx_gl_iswlower ifx_gl_iswprint ifx_gl_iswpunct ifx_gl_iswspace ifx_gl_iswupper ifx_gl_iswxdigit	Test the wide-character for the respective character classification.

**Character Case Conversion**
function	description
ifx_gl_case_conv_outbuflen	Calculates an approximation of the number of bytes for multi-byte case conversion.
ifx_gl_tomlower	Convert character to lower case.
ifx_gl_tomupper	Convert character to upper case.
ifx_gl_towlower	Transliterate upper-case wide-character code.
ifx_gl_towupper	Transliterate lower-case wide-character code.

**Character/String Comparison**
function	description
ifx_gl_mbscoll	String comparison using collating information.
ifx_gl_wcscoll	Wide-character string comparison using collating information.

**Code Set Conversion**
function	description
ifx_gl_conv_needed	Is code set conversion needed between the two code sets ?
ifx_gl_cv_mconv	Convert the string in the srccs code set to the dstcs code set.
ifx_gl_cv_outbuflen	Calculates an approximation of the number of bytes for codeset conversion.
ifx_gl_cv_sb2sb_table	Returns the single-byte conversion table from the srccs code set to the dstcs code set.

**Built-in Data Type Conversion**
function	description
ifx_gl_convert_date	Converts a date string into an internal representation.
ifx_gl_format_date	Converts a date value into a string with a given maximum length.
ifx_gl_convert_datetime	Converts a datetime string into an internal representation.
ifx_gl_format_datetime	Converts an internal datetime to a string with a given maximum length.
ifx_gl_convert_money	Converts a money string into an internal representation.
ifx_gl_format_money	Converts an internal representation of money to a string with a given maximum length.
ifx_gl_convert_number	Converts a numeric string into an internal representation.
ifx_gl_format_number	Converts an internal representation of a number to a string with a given maximum length.

**String Processing**
function	description
ifx_gl_mbscat	Concatenate two multibyte strings.
ifx_gl_mbschr	Multibyte string scanning operation.
ifx_gl_mbscpy	Copy a multibyte string.
ifx_gl_mbscspn	Get length of complementary multibyte substring.
ifx_gl_mbslen	Returns number of logical characters in a string.
ifx_gl_mbsmbs	Scan multibyte string for multibyte code.
ifx_gl_mbsncat	Concatenate part of two multibyte strings.
ifx_gl_mbsncpy	Copy part of a multibyte strings.
ifx_gl_mbsntsbytes	Returns number of bytes ignoring trailing spaces.
ifx_gl_mbsntslen	Returns logical characters ignoring trailing spaces.
ifx_gl_mbspbrk	Scan multibyte string for multibyte code.
ifx_gl_mbsrchr	Multibyte string scanning operation in reverse direction.
ifx_gl_mbsspn	Get length of multibyte substring.
ifx_gl_wcscat	Concatenate two wide character strings.
ifx_gl_wcschr	Wide character string scanning operation.
ifx_gl_wcscpy	Copy a wide character string.
ifx_gl_wcscspn	Get length of complementary wide character substring.
ifx_gl_wcslen	Get wide character string length.
ifx_gl_wcsncat	Concatenate part of two wide character strings.
ifx_gl_wcsncpy	Copy part of a wide character string.
ifx_gl_wcsntslen	Returns logical characters ignoring trailing spaces.
ifx_gl_wcspbrk	Scan wide character string for wide character.
ifx_gl_wcsrchr	Wide character string scanning operation in reverse direction.
ifx_gl_wcsspn	Get length of wide character substring.
ifx_gl_wcswcs	Find wide character substring.

**Multi-byte/Wide-character Conversion**
function	description
ifx_gl_mbstowcs	Convert a multi-byte character string to its wide-character.
ifx_gl_mbtowc	Convert one multi-byte character to its wide-character.
ifx_gl_wcstombs	Convert a wide-character string to its multi-byte character.
ifx_gl_wctomb	Convert one wide-character to its multi-byte character.

**Multibyte Memory Allocation**
function	description
ifx_gl_mb_loc_max	Returns size of the largest character in the locale.

**Multi-byte String Traversal and Indexing**
function	description
ifx_gl_mblen	Returns the number of bytes in a character.
ifx_gl_mbsnext	Returns the next multibyte character.
ifx_gl_mbsprev	Returns the previous multibyte character.

**Initialization and Error Handling**
function	description
ifx_gl_init	Ensures locale initialization.
ifx_gl_lc_errno	error value