                          DOCUMENTATION NOTES FOR
                    Informix Guide to GLS Functionality
                            DATE:  05/22/00
                             Version:  3.08

Table of Contents
I.   Overview
II.  Informix Database Server Names
III. Java Support
IV.  Glossary
V.   Inserting Localized Exception Messages from a C UDR
VI.  Unicode Universal Code Set (UCS) and Informix GLS

I.   OVERVIEW 
==============

This document describes feature and performance topics not covered in the
Informix Guide to GLS Functionality or modified since publication.


II.  INFORMIX DATABASE SERVER NAMES
===================================

This manual might not reflect the latest names of Informix database
servers. The following table lists the database server versions and their
corresponding names.

---------------------------------------------------------------------------
| Database Server    | Database Server Names                              |
| Version Numbers    |                                                    |
|-------------------------------------------------------------------------|
| 5.x                | INFORMIX OnLineINFORMIX SE and                     |
|                    | <vk>INFORMIX<Default ****Helvetica:xa6****         |
|                    | Font>****Helvetica:x15****<vk>SE                   |
|-------------------------------------------------------------------------|
| 7.1x, 7.2x         | INFORMIX OnLine Dynamic ServerINFORMIX SE and      |
|                    | <vk>INFORMIX<Default ****Helvetica:xa6****         |
|                    | Font>****Helvetica:x15****<vk>SE                   |
|-------------------------------------------------------------------------|
|  7.3x              | Informix Dynamic Server                            |
|-------------------------------------------------------------------------|
| 8.1x               | INFORMIX OnLine XPS                                |
|-------------------------------------------------------------------------|
| 8.2x               | Informix Dynamic Server with Advanced Decision     |
|                    | Support and Extended Parallel Options              |
|-------------------------------------------------------------------------|
| 8.3                | Informix Extended Parallel Server (XPS) or         |
|                    | Informix Enterprise Decision Server                |
|-------------------------------------------------------------------------|
| 9.01, 9.1 through  | INFORMIX-Universal Server                          |
| 9.13               |                                                    |
|-------------------------------------------------------------------------|
| 9.14               | Informix Dynamic Server with Universal Data Option |
|-------------------------------------------------------------------------|
| 9.2                | Informix Dynamic Server 2000                       |
---------------------------------------------------------------------------
 (<$tblsheetnum> of <$tblsheetcount>)


III. JAVA SUPPORT
=================

Informix Internet Foundation 2000 provides support for the following
Informix GLS environment varaibles: CLIENT_LOCALE, DB_LOCALE, GL_DATE, and
DBCENTURY. Informix Internet Foundation 2000 also provides support for the
following Informix GLS properties: GL_DATETIME and DB_TIME. For
information about Informix Internet Foundation 2000 and using these
environment variables with Java, see the documentation notes for Creating
UDRs in Java.


IV.  GLOSSARY
=============

The glossary that was formerly in the Informix Guide to GLS Functionality
is now in the Informix Guide to SQL: Reference.


V.   INSERTING LOCALIZED EXCEPTION MESSAGES FROM A C UDR
========================================================

To create messages for exceptions raised within UDRs (with
mi_db_error_raise()), insert them in the syserrors system catalog table.
For more information, see "Internationalized Exception Messages" on page 4-
17 of the 9.2 Informix Guide to GLS Functionality. However, to insert
these messages, the locale of the message text must match the server-
processing locale. If these locales are different, use of an SQL script or
a UDR (with mi_exec()) to insert the messages is not reliable. The SQL
parser triggers an error condition when it encounters characters that it
does not recognize.

To bypass this restriction, you can use a UDR that prepares the INSERT
statement (with mi_prepare()) to load the error messages. In the prepared
INSERT statement:

  o Use placeholders ('?' symbols) for the SQLSTATE value and the error-
    message text. 

    These values are in the first and last columns (sqlstate and message),
    respectively, of the syserrors system catalog table.

  o Hardcode the name of the locale that the message text uses.

    The locale name is in the second column (locale) of syserrors.

For example, the following line prepares an INSERT statement for messages
in the default locale of U.S. English (en_us) on a UNIX system:

    stmt = mi_prepare(conn, "insert into syserrors (?, 'en_us.8859-1', 0,
    1, ?)", NULL);
To execute this prepared INSERT statement, provide values for the
placeholders (sqlstate and message) and then use the
mi_exec_prepared_statement() function to send the INSERT to the database
server. (For more information on sending SQL statements with
mi_exec_prepared_statement(), see "Executing Prepared SQL Statements" on
page 8-16 of the 9.2 Informix DataBlade API Programmer's Manual.

The following UDR code uses a message array (enus_msg) to hold the
SQLSTATE values and their associated message text. It puts information
about each element of this message array in the approrpriate placeholder
arrays (args, lens, nulls, and types) of the mi_exec_prepared_statement()
function.

    #include <stdio.h>
    #include <string.h>
    #include "mi.h"
    #define MAX_MSG 3
    char *enus_msg[MAX_MSG][2] =  {
         "XT010", "First error message for insertion",
         "XT020", "Second error message for insertion",
         "XT030", "Third error message for insertion"
        };
    /*
     * Title: gls_insert_enus
     * Purpose: Add localized messages to the system error table 'syserrors'
     *          for given locale, independent of locale setting of session.
     */ 
    mi_integer
    gls_insert_enus()
    {
    MI_DATUM       args[2];                   /* pointers to column values
    */
    mi_integer     lens[2];                   /* lengths of column values */
    mi_integer     nulls[2];                  /* null capability of
    columns */
    mi_string     *types[2];                  /* types of columns */
    mi_integer     i;
    MI_STATEMENT  *stmt;
    MI_CONNECTION *conn = mi_open(NULL, NULL, NULL);
    /*
     * Prepare statement using placeholder values for sqlstate and message
     * columns while providing fixed values for locale, level, and seqno
    columns.
     */
    stmt = mi_prepare(conn,
             "insert into syserrors values(?,'en_us.8859-1',0,1,?)", NULL);
    for (i=0; i<MAX_MSG; i++)                 /* Loop through the message
    array */
    {
         args[0] = (MI_DATUM)enus_msg[i][0];   /* Set pointer to sqlstate
    string */
         lens[0] = strlen(args[0]);            /* Set length of sqlstate
    string */
         nulls[0] = MI_FALSE;                  /* Set null handling
    capability */
         types[0] = "char(5)";                 /* Set sqlstate column type
    */
         args[1] = (MI_DATUM)enus_msg[i][1];   /* Set pointer to message
    string */
         lens[1] = strlen(args[1]);            /* Set length of message
    string */
         nulls[1] = MI_FALSE;                  /* Set null handling
    capability */
         types[1] = "varchar(255)";            /* Set message column type */
        
    mi_exec_prepared_statement(stmt,0,0,2,args,lens,nulls,types,NULL,NULL);
    }
    mi_close(conn);
    return 0;
    }

VI.  UNICODE UNIVERSAL CODE SET (UCS) AND INFORMIX GLS
======================================================

To store data from more than one non-English language in one database, you
can either use the GLS implementation of the UTF-8 UCS GLS locale and code
set conversion files, or use the Unicode UCS in your database. To use
Unicode with Informix GLS, you must be using Informix Dynamic Server with
Universal Data Option (IDS/UD) Version 9.1x or above, and the Informix
Unicode DataBlade module. The Unicode DataBlade module enables users  to
store data in native Unicode format in a database and to access and
manipulate that data. For more information, see the Informix Unicode
DataBlade Module User's Guide. 

