cs_dt_info

Description

Sets or retrieves language-specific date, time, or datetime information.

Syntax

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;

Parameters

context: 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.

action: 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.

Value of action	cs_dt_info
CS_SET	Sets a date, time, or datetime conversion format.
CS_GET	Retrieves date, time or datetime information.

locale: 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.

type: The type of information of interest. Table 2-5 lists the symbolic values that are legal for type.

item: 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.

buffer: 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.

buflen: The length, in bytes, of *buffer.

If item is CS_12HOUR, pass buflen as CS_UNUSED.

outlen: 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.

Returns

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.

Usage

**Table 2-5: Summary of cs_dt_info parameter usage**
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

For more information on the common.loc file, 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, and CS_DATETIME4, value is converted to a character-based datatype.

Date:Table 2-6 lists the values that are legal for *buffer when type is CS_DT_CONVFMT:

**Table 2-6: Values for *buffer when type is CS_DT_CONVFMT (cs_dt_info)**
Symbolic value	CS_CHAR converted from CS_DATETIME, for example: Aug 24 1998 5:36PM	CS_CHAR converted from CS_DATE, for example: Aug 24 1998	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 1998 05:36:00:000PM	mon dd yyyy Aug 24 1998	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 1998 05:36:00:000PM	mon dd yyyy hh:mm:ss:zzz [AM\|PM] Aug 24 1998 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 1998 17:36:00	mon dd yyyy Aug 24 1998	hh:mm:ss 17:36:00
CS_DATES_ MDYHMS_ALT	mon dd yyyy hh:mm:ss Aug 24 1998 17:36:00	mon dd yyyy hh:mm:ss Aug 24 1998 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 1998 5:36PM	mon dd yyyy Aug 24 1998	hh:mm [AM\|PM] 5:36PM
CS_DATES_SHORT_ALT	mon dd yyyy hh:mm [AM\|PM] Aug 24 1998 5:36PM	mon dd yyyy hh:mm [AM\|PM] Aug 24 1998 12:00AM	mon dd yyyy hh:mm [AM\|PM] Jan 1 1900 5:36PM
CS_DATES_DMY1	dd/mm/yy 24/08/98	dd/mm/yy 24/08/98
CS_DATES_DMY1_YYYY	dd/mm/yyyy 24/08/1998	dd/mm/yyyy 24/08/1998
CS_DATES_DYM1	dd/yy/mm 24/98/08	dd/yy/mm 24/98/08
CS_DATES_DYM1_YYYY	dd/yyyy/mm 24/1998/08	dd/yy/mm 24/1998/08
CS_DATES_MDY1	mm/dd/yy 08/24/98	mm/dd/yy 08/24/98
CS_DATES_MDY1_YYYY	mm/dd/yyyy 08/24/1998	mm/dd/yyyy 08/24/1998
CS_DATES_MYD1	mm/yy/dd 08/98/24	mm/yy/dd 08/1998/24
CS_DATES_MYD1_YYYY	mm/yyyy/dd 08/1998/24	mm/yyyy/dd 08/1998/24
CS_DATES_YDM1	yy/dd/mm 98/24/08	yy/dd/mm 98/24/08
CS_DATES_YDM1_YYYY	yyyy/dd/mm 1998/24/08	yyyy/dd/mm 1998/24/08
CS_DATES_YMD1	yy.mm.dd 98.08.24	yy.mm.dd 98.08.24
CS_DATES_YMD1_YYYY	yyyy.mm.dd 1998.08.24	yyyy.mm.dd 1998.08.24
CS_DATES_DMY2	dd.mm.yy 24.08.98	dd.mm.yy 24.08.98
CS_DATES_DMY2_YYYY	dd.mm.yyyy 24.08.1998	dd.mm.yyyy 24.08.1998
CS_DATES_MDY2	mon dd, yy Aug 24,98	mon dd, yy Aug 24,98
CS_DATES_MDY2_YYYY	mon dd, yyyy Aug 24,1998	mon dd, yyyy Aug 24,1998
CS_DATES_YMD2	yy/mm/dd 98/08/24	yy/mm/dd 98/08/24
CS_DATES_YMD2_YYYY	yyyy/mm/dd 1998/08/24	yyyy/mm/dd 1998/08/24
CS_DATES_DMY3	dd-mm-yy 24-08-98	dd-mm-yy 24-08-98
CS_DATES_DMY3_YYYY	dd-mm-yyyy 24-08-1998	dd-mm-yyyy 24-08-1998
CS_DATES_MDY3	mm-dd-yy 08-24-98	mm-dd-yy 08-24-98
CS_DATES_MDY3_YYYY	mm-dd-yyyy 08-24-1998	mm-dd-yyyy 08-24-1998
CS_DATES_YMD3	yymmdd 980824	yymmdd 980824
CS_DATES_YMD3_YYYY	yyyymmdd 19980824	yyyymmdd 19980824
CS_DATES_YMDTHMS 23	yyyy-mm-ddThh:mm:ss 1998-08-24T17:36:00	yyyy-mm-dd 1998-08-24	hh:mm:ss 17:36:00
CS_DATES_DMY4	dd mon yy 24 Aug 98	dd mon yy 24 Aug 98
CS_DATES_DMY4_YYYY	dd mon yyyy 24 Aug 1998	dd mon yyyy 24 Aug 1998

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.