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