GLS Support

When the database server starts a UDR, the routine runs in the locale that DB_LOCALE specifies. Consequently, the database server automatically converts parameters, return values, and output values between the DB_LOCALE code set and the Unicode code set so that Java code can use the values.

However, when a Java UDR creates a JDBC connection to the database server for access through SQL, you can set DB_LOCALE into the connection URL to control conversions and formatting between the Unicode code set and the code set of the database server locale. This setting of DB_LOCALE overrides any environment settings. In fact, DB_LOCALE does not need to be set in the environment. Similarly, you can also set DBDATE, GL_DATE, and DBCENTURY into the URL connection to control date conversion and formatting.

For example, when a UDR sends string or date data to the database server in an insert, the database server converts the data from Unicode to the locale that DB_LOCALE specifies, or it interprets dates and intervals using your DBDATE or GL_DATE setting.

When the database server returns data to the Java UDR, the database server does the opposite conversion, so Java code sees only Unicode.

NEWLOCALE and NEWCODESET Connection Properties

IBM Informix JDBC Driver uses the JDK internationalization API to manipulate international data. The classes and methods in this API take a JDK locale or encoding as a parameter. Because the Informix DB_LOCALE and CLIENT_LOCALE properties specify the locale and code set based on Informix names, these Informix names are mapped to the JDK names. For example, the Informix and JDK names for the ASCII code set are 8859-1 and 8859_1 respectively. IBM Informix JDBC Driver internally maps 8859-1 to 8859_1 and uses the appropriate JDK name in the JDK classes and methods.

Two new connection properties, NEWLOCALE and NEWCODESET, enable you to specify a locale or code set that is not yet mapped in the internal tables of the JDBC driver.

The NEWLOCALE and NEWCODESET properties have the following formats:

NEWLOCALE=<JDK locale>,<Ifx locale>:<JDK locale>,<Ifx locale>...
NEWCODESET=<JDK encoding>,<Ifx codeset name>,
<Ifx codeset number>:<JDK encoding>,<Ifx codeset name>,<Ifx codeset number>...

The following example shows a URL that uses these properties. (You must specify a valid URL on a single line.)

jdbc:informix-sqli://myhost:1533:informixserver=myserver;user=myname;
password=mypasswd;NEWLOCALE=en_us,en_us;NEWCODESET=8859_1,8859-1,819;

There is no limit to the number of locale or code-set mappings that you can specify. If you specify an incorrect number of parameters or values, you get a message that says, "Locale Not Supported" or "Encoding or Code Set Not Supported." If you set these properties in the URL or in an IfmxDataSource object, the new values in NEWLOCALE and NEWCODESET override the values in the JDBC internal tables. For example, if JDBC already maps 8859-1 to 8859_1, but you specify NEWCODESET=8888,8859-1,819, the new value, 8888, is used for the code-set conversion.

DBCENTURY Environment Variable

If a String represents a DATE or a DATETIME value that has less than a three-digit year value, the IBM Informix JDBC Driver uses the DBCENTURY environment variable to determine the correct four-digit year and performs a String-to-DATE or -DATETIME conversion. For the DBCENTURY settings, the algorithms used, and examples, see the section on environment variables in the IBM Informix: Guide to SQL Reference.

The following table summarizes the affected methods and the conditions under which they are affected.

Method

Condition

IfxPreparedStatement.setString(String)

The target column is SQLDATE or SQLDTIME.

IfxPreparedStatement.setObject(String)

The target column is SQLDATE or SQLDTIME.

IfxPreparedStatement.IfxSetObject(String)

The target column is SQLDATE or SQLDTIME.

IfxResultSet.getDate()

The source column is a String type.

IfxResultSet.getTimestamp

The source column is a String type.

IfxResultSet.updateString(String)

The target column is SQLDATE or SQLDTIME.

IfxResultSet.updateObject(String)

The target column is SQLDATE or SQLDTIME.

The following example shows a URL that uses the DBCENTURY environment variable:

jdbc:informix-sqli://myhost:1533:informixserver=myserver;user=myname;password=
mypasswd;DBCENTURY=F;

You must specify a valid URL on a single line.