• DATE-format functions
• DATETIME-format functions
• Numeric-format functions
• String functions

DATE-Format Functions

• Support for the GL_DATE environment variable
• Support for era-based date formats of the DBDATE environment variable
• Extensions to the date-format strings for ESQL DATE-format functions
• Support for a precedence of date end-user formats

  ESQL/C Date Function	ESQL/COBOL Date Routine	Figure 7-1 ESQL DATE-Format Functions That Support Era-Based Extensions
  rdatestr()	ECO-DAT
  rstrdate()	ECO-STR
  rdefmtdate()	ECO-DEF
  rfmtdate()	ECO-FMT

GL_DATE Support

DBDATE Extensions

When you set DBDATE to one of the era-based formats, these functions use era-based dates to convert between date strings and internal DATE values. The following ESQL/C example shows a call to the rdatestr() library function:

char str[100];

long jdate;
.

.

.


rdatestr(jdate, str);

printf("%s\n", str);

H02/08/18

Important: Informix products treat any undefined characters in the alphabetic era specification as an error.

Extended DATE-Format Strings

Figure 7-4 shows the extended-format strings that these ESQL functions support for use with GLS locales.

Figure 7-4
Extended-Format Strings for GLS Locales

Era Year	Format	Era Used
Full era year: full name of the base year (period) followed by a 2-digit year offset Same as GL_DATE end-user format of "%EC%02.2Ey"	eyy	The era that the client locale (that CLIENT_LOCALE indicates) defines
Abbreviated era year: abbreviated name of the base year (period) followed by a 2-digit year offset Same as GL_DATE end-user format of "%Eg%02.2Ey"	gyy	The era that the client locale (that CLIENT_LOCALE indicates) defines

The extended-format strings in Figure 7-4 format eras with 2-digit year offsets. To obtain a 4-digit year offset, use the c1, j1, or j2 extended-format strings (see Figure 7-6).

Figure 7-5 shows some sample extended-format strings for era-based dates.

Figure 7-5
Sample Extended-Format Strings for GLS Locales

Description	Sample Format	October 5, 1990 prints as:
Abbreviated era year	gyymmdd gyy.mm.dd	H021005 H02.10.05
Full era year	eyymmdd eyy-mm-dd eyyB1B2mmB1B2ddB1B2	A1A2021005 A1A202-10-05 A1A202B1B210B1B205B1B2

The examples in Figure 7-5 assume that the client locale is Japanese SJIS (ja_jp.sjis).

The following ESQL/C code fragment contains a call to the rdefmtdate() library function:

char fmt_str[100];

char in_str[100];

long jdate;
.

.

.


rdatestr("10/05/95", &jdate);

stcopy("gyy/mm/dd", fmt_str);

rdefmtdate(&jdate, fmt_str, in_str);

printf("Abbreviated Era Year: %s\n", in_str);



stcopy("eyymmdd", fmt_str);

rdefmtdate(&jdate, fmt_str, in_str);

printf("Full Era Year: %s\n", in_str);

Abbreviated Era Year: H07/10/05

Full Era Year: H021005

Figure 7-6 shows the extended-format strings that these ESQL functions support for backward compatibility with ALS Version 5.0 products.

Figure 7-6
Extended-Format Strings for ALS Version 5.x Compatibility

Era Year	Format	Era Used
Full era year: full name of the base year (period) followed by a 2-digit year offset Same as GL_DATE end-user format of "%EC%02.2Ey"	yyj2	Japanese Imperial
Full era year: full name of the base year (period) followed by a 4-digit year offset Same as GL_DATE end-user format of "%EC%04.4Ey"	yyyyj2	Japanese Imperial
Abbreviated era year: abbreviated name of the base year (period) followed by a 2-digit year offset Same as GL_DATE end-user format of "%Eg%02.2Ey"	yyc1 yyj1	Taiwanese Ming Guo Japanese Imperial
Abbreviated era year: abbreviated name of the base year (period) followed by a 4-digit year offset Same as GL_DATE end-user format of "%Eg%04.4Ey"	yyyyc1 yyyyj1	Taiwanese Ming Guo Japanese Imperial

The following table shows some sample ALS Version 5.0 extended-format strings for era-based dates.

Description	Sample Format	October 5, 1990 prints as:
Japanese era: abbreviated era year, 2-digit year abbreviated era year, 4-digit year full era year, 2-digit year full era year, 4-digit year	yymmddj1 yyyymmddj1 yymmddj2 yyyymmddj2	H021005 H00021005 A1A2021005 A1A200021005
Taiwanese Ming Guo date: with 2-digit year with 4-digit year	yymmddc1 yy.mm.ddc1 yyA1A2mmA1A2ddA1A2 yyyymmddc1	791005 79.10.05 79A1A210A1A205A1A2 00791005

Figure 7-7 shows the extended-format strings that these ESQL functions support for backward compatibility with ALS Version 4.x products.

Figure 7-7
Extended-Format Strings for ALS 4.x Compatibility

Era Format	Format	Locale
Full era year: full name of the base year (period) followed by a 2-digit year offset Same as GL_DATE end-user format of "%EC%02.2Ey"	nnnnyy	Japanese
Abbreviated era year: abbreviated name of the base year (period) followed by a 2-digit year offset Same as GL_DATE end-user format of "%Eg%02.2Ey"	nyy	Japanese
Day of the week, with symbols that the locale defines (Sunday through Saturday in Asian characters). Multibyte characters are printed if DB_LOCALE is set to another language.	ww

The following table shows some sample ALS Version 4.x extended-format strings for era-based dates.

Description	Sample Format	October 5, 1990 prints as:
Japanese era: abbreviated era year full era year	nyymmdd nnnnyy mm dd nnnnyymmdd (ww)	H021005 A1A202 10 05 A1A2021005 (B1B2)

In addition to the era-based combinations in Figures 7-4 through Figure 7-7, the format string also supports the combinations that the INFORMIX-ESQL/C Programmer's Manual and the INFORMIX-ESQL/COBOL Programmer's Manual describe for these functions.

Precedence for Date End-User Formats

1. The end-user format that DBDATE specifies (if DBDATE is set)

2. The end-user format that GL_DATE specifies (if GL_DATE is set)

3. The date end-user format that the client locale specifies (if CLIENT_LOCALE is set)

4. The date end-user form from the default locale: %m %d %iY

Tip: Informix products support DBDATE for backward compatibility with earlier products. Informix recommends the use of the GL_DATE environment variable for new client applications.

DATETIME-Format Functions

• Support for the GL_DATETIME environment variable
• Support for era-based date and times of the DBTIME environment variable
• Extensions to the date and time format strings for ESQL DATETIME-format functions
• Support for a precedence of DATETIME end-user formats

  ESQL/C DATETIME Function	ESQL/COBOL DATETIME Routine	Figure 7-8 ESQL DATETIME-Format Functions That Support Era-Based Extensions
  dtcvfmtasc()	ECO-DTCVASC
  dttofmtasc()	ECO-DTTOASC

GL_DATETIME Support

DBTIME Support

When you set DBTIME to one of the era-based formats, these functions can use era-based dates and times to convert between literal DATETIME strings and internal DATETIME values.

Tip: Informix products support DBTIME for backward compatibility with earlier products. Informix recommends the use of the GL_DATETIME environment variable for new applications.

If you set DBTIME to a era-based DATETIME format (that is specific to a Chinese or Japanese locale), make sure to set the CLIENT_LOCALE environment variable to a locale that supports era-based dates and times.

Extended DATETIME-Format Strings

In addition to the formats in the preceding table, these ESQL DATETIME-format functions support the GLS date and time specifiers. For a list of these specifiers, see the description of the GL_DATE and GL_DATETIME environment variables in Chapter 2, "GLS Environment Variables."

Precedence for DATETIME End-User Formats

1. The end-user format that DBTIME specifies (if DBTIME is set)

2. The end-user format that GL_DATETIME specifies (if GL_DATETIME is set)

3. The date and time end-user formats that the client locale specifies (if CLIENT_LOCALE is set)

4. The date and time end-user format from the default locale: %iY-%m-%d %H:%M:%S

Numeric-Format Functions

• Support for multibyte characters in format strings
• Locale-specific formats for numeric values
• Formatting characters for currency symbols
• Support for the DBMONEY environment variable

  ESQL/C Numeric Function	ESQL/COBOL Numeric Routine	Figure 7-9 ESQL Numeric-Format Functions That Support Extended Numeric Formats
  rfmtdec()	None
  rfmtdouble()	ECO-FEL
  rfmtlong()	ECO-FIN

Tip: For a list of errors that these ESQL numeric-format functions might return, see "GLS-Specific Error Messages".

Support for Multibyte Characters

For example, the following ESQL/C code fragment shows a call to the rfmtlong() function with the multibyte character A1A2 in the format string:

stcopy("A1A2***,***", fmtbuf);

rfmtlong(78941, fmtbuf, outbuf);

printf("Formatted value: %s\n", outbuf);

Formatting value: A1A2*78,941

Formatting Character	Function
Dollar sign ($)	Currency symbol
Comma (,)	Thousands separator
Period (.)	Decimal separator

Regardless of the client locale that you use, you must use the preceding ASCII symbols in the format string to identify where to place the currency symbol, decimal separator, and thousands separator. The numeric-format function uses the following precedence to translate these symbols to their locale-specific equivalents:

1. The symbols that DBMONEY indicates (if DBMONEY is set)

For locale-specific behavior of DBMONEY, see "DBMONEY Extensions".

2. The symbols that the appropriate locale category of the client locale (if CLIENT_LOCALE is set) specifies

For more information on the use of the $ and @ formatting characters, see "Currency-Symbol Formatting". For more information on the MONETARY and NUMERIC locale categories, see "Locale Categories".

3. The actual symbol that appears in the format string ($, comma, or period)

For example, the following ESQL/C code fragment shows a call to the rfmtlong() function:

stcopy("$***,***.&&", fmtbuf);

rfmtlong(78941, fmtbuf, outbuf);

printf("Formatted value: %s\n", outbuf);

Currency-Symbol Formatting

For more information, see "The MONETARY Category".

You can include both formatting characters in a format string. The locale defines whether the currency symbol appears before or after the monetary value, as follows:

• If the locale formats monetary values with a currency symbol before the value, the locale sets the currency symbol to the precede-currency symbol and sets the succeed-currency symbol to a blank character.
• If the locale formats monetary values with a currency symbol after the value, the locale sets the currency symbol to the succeed-currency symbol and sets the precede-currency symbol to a blank character.

In the preceding table, the character s represents a blank or space, the FF is the French currency symbol for French francs, and the DM is the German currency symbol for deutsche marks. For more information on locale-specific currency notation, see page 7-18.

The DBMONEY environment variable can also set the precede-currency symbol and the succeed-currency symbol. The syntax diagram for DBMONEY (see page 2-19) refers to these symbols as front and back, respectively. If set, DBMONEY takes precedence over the symbols that the locale defines.

DBMONEY Extensions

You can use multibyte characters for these symbols, as long as your client code set supports them. For example, the following table shows how multibyte characters appear in sample output.

Format String	Number to be Formatted	DBMONEY	Output
"$$,$$$.$$"	1234	'$'.	$1,234.00
"$$,$$$.$$"	1234	DM,	DM1.234,00
"$$,$$$.$$"	1234	A1A2.	A1A21,234.00
"$$,$$$.$$"	1234	.A1A2	s1,234.00
"&&,&&&.&&@"	1234	.A1A2	s1,234.00A1A2
"$&&,&&&.&&@"	1234	A1A2.	A1A2s1,234.00
"$&&,&&&.&&@"	1234	.A1A2	s1,234.00A1A2
"@&&,&&&.&&"	1234	.A1A2	A1A2s1,234.00

In the preceding table, the character s represents a blank or space. For more information on DBMONEY, see page 2-19.

String Functions

These string functions use the information in the CTYPE category of the client locale to determine the shifted code points. (For more information on the CTYPE locale category, see page A-6.) If the client locale specifies a multibyte code set, these functions can operate on multibyte strings.

Important: With multibyte character strings, a shifted string might occupy more memory after a shift operation than it did before. You must ensure that the buffer you pass to these ESQL shift functions is large enough to accommodate this expansion.

GLS-Specific Error Messages

The following ESQL functions might generate GLS-specific error messages:

• DATE-format functions (see Figure 7-1)
• DATETIME-format functions (see Figure 7-8)
• Numeric-format functions (see Figure 7-9)