Sets or retrieves language-specific date, time, or datetime information.
CS_RETCODE cs_dt_info(context, action, locale, type,
item, buffer, buflen, outlen)
CS_CONTEXT *context;
CS_INT action;
CS_LOCALE *locale;
CS_INT type;
CS_INT item;
CS_VOID *buffer;
CS_INT buflen;
CS_INT *outlen;
A pointer to a CS_CONTEXT structure.
When retrieving date, time, or datetime information, if locale is NULL, cs_dt_info uses the default locale information contained in this context structure.
One of the following symbolic values:
Value of action |
cs_dt_info |
|---|---|
CS_SET |
Sets a date, time, or datetime conversion format. |
CS_GET |
Retrieves date, time or datetime information. |
A pointer to a CS_LOCALE structure. A locale structure contains locale information, including datetime information.
When setting datetime information, locale must be supplied.
When retrieving datetime information, locale can be NULL. If locale is NULL, cs_dt_info uses the default locale information contained in *context.
The type of information of interest. Table 2-7 lists the symbolic values that are legal for type.
When retrieving information, item is the item number of the type category to retrieve. For example, to retrieve the name of the first month, an application passes type as CS_MONTH and item as 0.
When setting a datetime conversion format, pass item as CS_UNUSED.
If datetime information is being retrieved, buffer points to the space in which cs_dt_info will place the requested information.
If buflen indicates that *buffer is not large enough to hold the requested information, cs_dt_info sets *outlen to the length of the requested information and returns CS_FAIL.
If a datetime conversion format is being set, buffer points to a symbolic value representing a conversion format.
The length, in bytes, of *buffer.
If item is CS_12HOUR, pass buflen as CS_UNUSED.
A pointer to an integer variable.
cs_dt_info sets *outlen to the length, in bytes, of the requested information.
If the requested information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.
cs_dt_info returns:
Returns |
Indicates |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
The most common reason for a cs_dt_info failure is an invalid parameter.
Value of type |
cs_dt_info |
action can be |
item can be |
*buffer is |
|---|---|---|---|---|
CS_MONTH |
Retrieves the month name string. |
CS_GET |
0–11 |
A character string. |
CS_SHORTMONTH |
Retrieves the short month name string. |
CS_GET |
0–11 |
A character string. |
CS_DAYNAME |
Retrieves the day name string. |
CS_GET |
0–6 |
A character string. |
CS_DATEORDER |
Retrieves the date order string. |
CS_GET |
CS_UNUSED |
A string containing the three characters “m,” “d,” and “y” to indicate the position of the month, day, and year in the datetime format. |
CS_12HOUR |
Retrieves whether or not the language uses 12-hour time formats. |
CS_GET |
CS_UNUSED |
CS_TRUE if 12-hour formats are used; CS_FALSE if 24-hour formats are used. |
CS_DT_CONVFMT |
Sets or retrieves the datetime conversion format. |
CS_GET or CS_SET |
CS_UNUSED |
A symbolic value. See the Comments section, below, for a list of possible values. |
cs_dt_info sets or retrieves native language-specific datetime information:
cs_dt_info can return native language date part names, date part ordering information, datetime format information, and whether or not the language uses 12-hour date formats.
cs_dt_info can set datetime format information.
If locale is NULL, cs_dt_info looks for native language locale information in *context. An application can set locale information for a CS_CONTEXT by calling cs_config with property as CS_LOC_PROP.
If not specifically set, locale information in a CS_CONTEXT defaults to information that CS-Library picks up from the operating system when the context is allocated. If locale information is not available from the operating system, CS-Library uses platform-specific localization values in the new context.
A locale’s date-order string, which can be retrieved by calling cs_dt_info with type as CS_DATEORDER, describes how ambiguous date strings are resolved when converting from character datatypes to CS_DATE, CS_DATETIME or CS_DATETIME4. For example, “04/05/96” could be interpreted as “April 5, 1996” or “May 4, 1996.” The former result corresponds to the date-order string of “mdy”, and the latter corresponds to “dmy.”
Although an application cannot set a locale’s date-order string directly, it can call cs_locale and change the national-language used when converting dates. To do this, the application calls cs_locale with action as CS_SET, type as CS_LC_TIME, and *buffer as a locale name. The application can specify a locale whose national language is configured to use a different date-order string. A national language’s date-order string is configured as follows:
For each national language, a common.loc file is located in a language subdirectory in the $SYBASE/locales/messages subdirectory.
The “dateformat” setting in the [datetime] section of the file specifies the date-order string. For example:
[datetime]
dateformat=dmy
See the Open Client and Server Configuration Guide for Microsoft Windows or Open Client and Server Configuration Guide for UNIX.
The date conversion format, which can be set or retrieved by calling cs_dt_info with type as CS_DT_CONVFMT, describes the format of the result when a CS_DATE, CS_TIME, CS_DATETIME, CS_DATETIME4, CS_BIGDATETIME or CS_BIGTIME value is converted to a character-based datatype.
Table 2-8 lists the values that are legal for *buffer when type is CS_DT_CONVFMT in conversions from CS_CHAR to CS_DATETIME, CS_DATE, or CS_TIME. This conversion format is also used to describe results when a character string is converted to any of these datetime datatypes.
Symbolic value |
CS_CHAR converted from CS_DATETIME, for example: Aug 24 2009 5:36PM |
CS_CHAR converted from CS_DATE, for example: Aug 24 2009 |
CS_CHAR converted from CS_TIME, for example: 5:36PM |
|---|---|---|---|
CS_DATES_HM |
hh:mm 17:36 |
hh:mm 00:00 |
hh:mm 17:36 |
CS_DATES_HMA |
hh:mm[AM|PM] 5:36PM |
hh:mm 12:00AM |
hh:mm 5:36PM |
CS_DATES_HMS |
hh:mm:ss 17:36:00 |
hh:mm:ss 00:00:00 |
hh:mm:ss 17:36:00 |
CS_DATES_HMS_ ALT |
hh:mm:ss 17:36:32 |
hh:mm:ss 00:00:00 |
hh:mm:ss 17:36:32 |
CS_DATES_HMSZA |
hh:mm:ss:zzz[AM|PM] 5:36:00:000PM |
hh:mm:ss:zzz[AM|PM] 12:00:00:000AM |
hh:mm:ss:zzz[AM|PM] 5:36:00:000PM |
CS_DATES_HMSZ |
hh:mm:ss:zzz 17:36:00:000 |
hh:mm:ss:zzz 00:00:00:000 |
hh:mm:ss:zzz 17:36:00:000 |
CS_DATES_LONG |
mon dd yyyy hh:mm:ss:zzz [AM|PM] Aug 24 2009 05:36:00:000PM |
mon dd yyyy Aug 24 2009 |
hh:mm:ss:zzz [AM|PM] 05:36:00:000PM |
CS_DATES_LONG_ ALT |
mon dd yyyy hh:mm:ss:zzz [AM|PM] Aug 24 2009 05:36:00:000PM |
mon dd yyyy hh:mm:ss:zzz [AM|PM] Aug 24 2009 12:00:00:000 AM |
mon dd yyyy hh:mm:ss:zzz [AM|PM] Jan 01 1900 05:36:00:000 PM |
CS_DATES_ MDYHMS |
mon dd yyyy hh:mm:ss Aug 24 2009 17:36:00 |
mon dd yyyy Aug 24 2009 |
hh:mm:ss 17:36:00 |
CS_DATES_ MDYHMS_ALT |
mon dd yyyy hh:mm:ss Aug 24 2009 17:36:00 |
mon dd yyyy hh:mm:ss Aug 24 2009 00:00:00 |
mon dd yyyy hh:mm:ss Jan 1 1900 17:36:00 |
CS_DATES_SHORT |
mon dd yyyy hh:mm [AM|PM] Aug 24 2009 5:36PM |
mon dd yyyy Aug 24 2009 |
hh:mm [AM|PM] 5:36PM |
CS_DATES_SHORT_ALT |
mon dd yyyy hh:mm [AM|PM] Aug 24 2009 5:36PM |
mon dd yyyy hh:mm [AM|PM] Aug 24 2009 12:00AM |
mon dd yyyy hh:mm [AM|PM] Jan 1 1900 5:36PM |
CS_DATES_DMY1 |
dd/mm/yy 24/08/09 |
dd/mm/yy 24/08/09 |
|
CS_DATES_DMY1_YYYY |
dd/mm/yyyy 24/08/2009 |
dd/mm/yyyy 24/08/2009 |
|
CS_DATES_DYM1 |
dd/yy/mm 24/09/08 |
dd/yy/mm 24/09/08 |
|
CS_DATES_DYM1_YYYY |
dd/yyyy/mm 24/2009/08 |
dd/yy/mm 24/2009/08 |
|
CS_DATES_MDY1 |
mm/dd/yy 08/24/09 |
mm/dd/yy 08/24/09 |
|
CS_DATES_MDY1_YYYY |
mm/dd/yyyy 08/24/2009 |
mm/dd/yyyy 08/24/2009 |
|
CS_DATES_MYD1 |
mm/yy/dd 08/09/24 |
mm/yy/dd 08/2009/24 |
|
CS_DATES_MYD1_YYYY |
mm/yyyy/dd 08/2009/24 |
mm/yyyy/dd 08/2009/24 |
|
CS_DATES_YDM1 |
yy/dd/mm 09/24/08 |
yy/dd/mm 09/24/08 |
|
CS_DATES_YDM1_YYYY |
yyyy/dd/mm 2009/24/08 |
yyyy/dd/mm 2009/24/08 |
|
CS_DATES_YMD1 |
yy.mm.dd 09.08.24 |
yy.mm.dd 09.08.24 |
|
CS_DATES_YMD1_YYYY |
yyyy.mm.dd 2009.08.24 |
yyyy.mm.dd 2009.08.24 |
|
CS_DATES_DMY2 |
dd.mm.yy 24.08.09 |
dd.mm.yy 24.08.09 |
|
CS_DATES_DMY2_YYYY |
dd.mm.yyyy 24.08.2009 |
dd.mm.yyyy 24.08.2009 |
|
CS_DATES_MDY2 |
mon dd, yy Aug 24,09 |
mon dd, yy Aug 24,09 |
|
CS_DATES_MDY2_YYYY |
mon dd, yyyy Aug 24,2009 |
mon dd, yyyy Aug 24,2009 |
|
CS_DATES_YMD2 |
yy/mm/dd 09/08/24 |
yy/mm/dd 09/08/24 |
|
CS_DATES_YMD2_YYYY |
yyyy/mm/dd 2009/08/24 |
yyyy/mm/dd 2009/08/24 |
|
CS_DATES_DMY3 |
dd-mm-yy 24-08-09 |
dd-mm-yy 24-08-09 |
|
CS_DATES_DMY3_YYYY |
dd-mm-yyyy 24-08-2009 |
dd-mm-yyyy 24-08-2009 |
|
CS_DATES_MDY3 |
mm-dd-yy 08-24-09 |
mm-dd-yy 08-24-09 |
|
CS_DATES_MDY3_YYYY |
mm-dd-yyyy 08-24-2009 |
mm-dd-yyyy 08-24-2009 |
|
CS_DATES_YMD3 |
yymmdd 090824 |
yymmdd 090824 |
|
CS_DATES_YMD3_YYYY |
yyyymmdd 20090824 |
yyyymmdd 20090824 |
|
CS_DATES_YMDTHMS 23 |
yyyy-mm-ddThh:mm:ss 2009-08-24T17:36:00 |
yyyy-mm-dd 2009-08-24 |
hh:mm:ss 17:36:00 |
CS_DATES_DMY4 |
dd mon yy 24 Aug 09 |
dd mon yy 24 Aug 09 |
|
CS_DATES_DMY4_YYYY |
dd mon yyyy 24 Aug 2009 |
dd mon yyyy 24 Aug 2009 |
Table 2-9 lists the values that are legal for *buffer when type is CS_DT_CONVFMT in conversions between CS_CHAR and CS_BIGDATETIME and CS_BIGTIME:
Symbolic value |
CS_CHAR converted from CS_BIGDATETIME, for example: Aug 24 2009 5:36PM |
CS_CHAR converted from CS_BIGTIME, for example: 5:36PM |
|---|---|---|
CS_DATES_ HMSUSA, or CS_DATES_ HMSUSA_YYYY |
hh:mm:ss.zzzzzz[AM|PM] 5:36:00.000000PM |
hh:mm:ss.zzzz[AM|PM] 5:36:00.000000PM |
CS_DATES_ HMSUS, or CS_DATES_ HMSUS_YYYY |
hh:mm:ss.zzzzzz 17:36:00.000000 |
hh:mm:ss.zzzzzz 17:36:00.000000 |
CS_DATES_ LONGUSA |
mon dd yy hh:mm:ss.zzzzzz[AM|PM] Aug 24 09 5:36:00.000000PM |
mon dd yy hh:mm:ss.zzzzzz[AM|PM] Jan 1 01 5:36:00.000000PM |
CS_DATES_ LONGUSA_YYYY |
mon dd yyyy hh:mm:ss.zzzzzz[AM|PM] Aug 24 2009 5:36:00.000000PM |
mon dd yyyy hh:mm:ss.zzzzzz[AM|PM] Jan 1 0001 5:36:00.000000PM |
CS_DATES_ LONGUS |
mon dd yy hh:mm:ss.zzzzzz Aug 24 09 17:36:00.000000 |
mon dd yy hh:mm:ss.zzzzzz Jan 1 01 17:36:00.000000 |
CS_DATES_ LONGUS_YYYY |
mon dd yyyy hh:mm:ss.zzzzzz Aug 24 2009 17:36:00.000000 |
mon dd yy hh:mm:ss.zzzzzz Jan 0 0001 17:36:00.000000 |
CS_DATES_ YMDHMSUS_YYYY |
yyyy-mm-dd hh:mm:ss.zzzzzz 2009-08-24 17:36:00.000000 |
yyyy-mm-dd hh:mm:ss.zzzzzz 0001-01-01 17:36:00.000000 |
A cs_locale (CS_SET, CS_LC_TIME) call or a cs_locale (CS_SET, CS_LC_ALL) call resets date/time conversion information to the default settings for the specified national language.
