GetDateFormat Function

Declare Function GetDateFormat Lib "kernel32.dll" Alias "GetDateFormatA" (ByVal Locale As Long, ByVal dwFlags As Long, lpDate As SYSTEMTIME, ByVal lpFormat As Any, ByVal lpDateStr As String, ByVal cchDate As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.5 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

GetDateFormat formats a string to display a date according to a locale's settings. The date can be formatted using either a predefined format or a custom format specified in the parameter list. The string generated by this function can be used to present a more human-readable way to display a date.

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the size in bytes of the string placed into the variable passed as lpDateStr.

Visual Basic-Specific Issues

When passing 0 for the lpFormat parameter, the expression CLng(0) must be used.

Parameters

Locale

The identifier of the locale to use to format the string as necessary. If this is 0, the locale of the calling thread is used. This can also be one of the following flags specifying a default locale:

LOCALE_SYSTEM_DEFAULT: The system's default locale.
LOCALE_USER_DEFAULT: The user's default locale.

dwFlags

A combination of the following flags specifying how to format the date string. If a format string is passed as lpFormat, this parameter must be set to 0.

LOCALE_NOUSEROVERRIDE: Use the system's default date format for the specified locale, ignoring any changes to those defaults which the user may have selected.
LOCALE_USE_CP_ACP: Use the system's ANSI code page for string translation instead of the locale's code page.
DATE_SHORTDATE: Format the date string using the short date format.
DATE_LONGDATE: Format the date string using the long date format.
DATE_YEARMONTH: Format the date string using the year/month date format.
DATE_USE_ALT_CALENDAR: If an alternate calendar exists, use the default date format of that calendar to format the date string.
DATE_LTRREADING: Add marks for left-to-right reading layout.
DATE_RTLREADING: Add marks for right-to-left reading layout.

lpDate

The date to format as a string. The members of the structure which specify the time are ignored.

lpFormat

The format template string used to generate the date string. To use one of the predefined formats, this parameter must be 0. In a format template string, the following series of characters stand for the following components of the date:

d: The day of the month as digits without a leading zero for single-digit days.
dd: The day of the month as digits with a leading zero for single-digit days.
ddd: The three-letter abbreviation for the name of the day of the week.
dddd: The full name of the day of the week.
M: The month as digits without a leading zero for single-digit months.
MM: The month as digits with a leading zero for single-digit months.
MMM: The three-letter abbreviation for the name of the month.
MMMM: The full name of the month.
y: The last two digits of the year without a leading zero for years between ??00-??09.
yy: The last two digits of the year with a leading zero for years between ??00-??09.
yyyy: All four digits of the year.
gg: The period/era string, if defined for the locale. If it is not defined, this string is ignored.

Any spaces appearing in the template string appear verbatim in the formatted string. To place any other "fixed" characters or text in the format string, you must enclose the literal text in single quotation marks.

lpDateStr

Receives the formatted date string. This must initally be sufficiently long to receive the string.

cchDate

The length of the string passed as lpDateStr.

Constant Definitions

Const LOCALE_SYSTEM_DEFAULT = &H400
Const LOCALE_USER_DEFAULT = &H800
Const LOCALE_NOUSEROVERRIDE = &H80000000
Const LOCALE_USE_CP_ACP = &H40000000
Const DATE_SHORTDATE = &H1
Const DATE_LONGDATE = &H2
Const DATE_USE_ALT_CALENDAR = &H4
Const DATE_YEARMONTH = &H8
Const DATE_LTRREADING = &H10
Const DATE_RTLREADING = &H20

Example

' This code is licensed according to the terms and conditions listed here.

' Display today's date first in the default Long Date format and
' then in the standard HTTP date format.
Dim today As SYSTEMTIME  ' today's date and time
Dim datestr As String  ' receives the formatted date string
Dim strlen As Long  ' length of the buffer for the formatted date string

' Get today's date and time in the local time zone.
GetLocalTime today

' Make sufficient room in the buffer to receive the date string.
datestr = Space(255)
' Format today's date as a Long Date.
strlen = GetDateFormat(0, DATE_LONGDATE, today, CLng(0), datestr, Len(datestr))
' Remove the empty space from the formatted date string.
datestr = Left(datestr, strlen)
' Display today's date as a Long Date.
Debug.Print "Today is "; datestr

' Now make sufficient room once again.
datestr = Space(255)
' Format today's date in the format used in HTTP.
strlen = GetDateFormat(0, 0, today, "ddd',' dd MMM yyyy", datestr, Len(datestr))
' Remove the empty space from the formatted string.
datestr = Left(datestr, strlen)
' Display today's date in the HTTP-style format.
Debug.Print "Today is "; datestr