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

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

See Also

GetTimeFormat

Category

National Language Support

Go back to the alphabetical Function listing.
Go back to the Reference section index.


Last Modified: January 1, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/g/getdateformat.html