GetCalendarDateFormatEx function

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.


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


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.


Use the short date format. This is the default. This value cannot be used with DATE_LONGDATE or DATE_YEARMONTH.


Use the long date format. This value cannot be used with DATE_SHORTDATE or DATE_YEARMONTH.


Use the year/month format. This value cannot be used with DATE_SHORTDATE or DATE_LONGDATE.


Add marks for left-to-right reading layout. This value cannot be used with 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.


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.


Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]



See also

National Language Support
National Language Support Functions
Day, Month, Year, and Era Format Pictures
NLS: Name-based APIs Sample