GetCalendarDateFormatEx function

Article
01/07/2021

Deprecated. Retrieves a properly formatted date string for the specified locale using the specified date and calendar. The user can specify the short date format, the long date format, the year month format, or a custom format pattern.

Note

This function can retrieve data that changes between releases, for example, due to a custom locale. If your application must persist or transmit data, see Using Persistent Locale Data.

Syntax

BOOL GetCalendarDateFormatEx(
  _In_        LPCWSTR       lpszLocale,
  _In_        DWORD         dwFlags,
  _In_  const LPCALDATETIME lpCalDateTime,
  _In_        LPCWSTR       lpFormat,
  _Out_       LPWSTR        lpDateStr,
  _In_        int           cchDate
);

Parameters

lpszLocale [in]

Pointer to a locale name, or one of the following predefined values.

dwFlags [in]

Flags specifying date format options. If lpFormat is not set to NULL, this parameter must be set to 0. If lpFormat is set to NULL, the application can specify a combination of the following values and LOCALE_NOUSEROVERRIDE.

Value	Meaning
DATE_SHORTDATE	Use the short date format. This is the default. This value cannot be used with DATE_LONGDATE or DATE_YEARMONTH.
DATE_LONGDATE	Use the long date format. This value cannot be used with DATE_SHORTDATE or DATE_YEARMONTH.
DATE_YEARMONTH	Use the year/month format. This value cannot be used with DATE_SHORTDATE or DATE_LONGDATE.
DATE_LTRREADING	Add marks for left-to-right reading layout. This value cannot be used with DATE_RTLREADING.
DATE_RTLREADING	Add marks for right-to-left reading layout. This value cannot be used with DATE_LTRREADING

lpCalDateTime [in]

Pointer to a CALDATETIME structure that contains the date and calendar information to format.

lpFormat [in]

Pointer to a format picture string that is used to form the date string. Possible values for the format picture string are defined in Day, Month, Year, and Era Format Pictures.

The format picture string must be null-terminated. The function uses the locale only for information not specified in the format picture string, for example, the day and month names for the locale. The application sets this parameter to NULL if the function is to use the date format of the specified locale.

lpDateStr [out]

Pointer to a buffer in which this function receives the formatted date string.

cchDate [in]

Size, in characters, of the lpDateStr buffer. Alternatively, the application can set this parameter to 0. In this case, the function returns the number of characters required to hold the formatted date string, and the lpDateStr parameter is not used.

Return value

Returns the number of characters written to the lpDateStr buffer if successful. If the cchDate parameter is set to 0, the function returns the number of characters required to hold the formatted date string, including the terminating null character.

This function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:

ERROR_DATE_OUT_OF_RANGE. The specified date was out of range.
ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.

Remarks

The earliest date supported by this function is January 1, 1601.

This function does not have an associated header file or library file. The application can call LoadLibrary with the DLL name (Kernel32.dll) to obtain a module handle. It can then call GetProcAddress with that module handle and the name of this function to get the function address.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
DLL	Kernel32.dll