GetDateItemDate Function Documentation

Overview

GetDateItemDate converts the date item's internal FILETIME to a SQL DATE_STRUCT (year/month/day) via GetDateFromFiletime() and stores it in the caller-supplied structure.

Purpose

DATE_STRUCT (declared in <sqltypes.h>, which datelog.h includes) is the calendar form used for ODBC parameters and for date-based lookups such as FindDateItemByDate. This function gives callers that representation without manual FILETIME arithmetic. Use GetDateItemFiletime(), GetDateItemSystemTime(), or GetDateItemLargeInteger() when a different representation is required.

Function Signature


BOOL _Check_return_ _Success_(return == TRUE) GetDateItemDate(
    _In_  DATE_ITEM_HANDLE hDateItem,
    _Out_ DATE_STRUCT *    pDate
);

Parameters

hDateItem

[In] DATE_ITEM_HANDLE

The date item to query.

NULL: not allowed; the function returns FALSE.
Valid values: an initialized date item, either standalone or resident in a collection. An item whose internal FILETIME is zero/uninitialized is rejected.
Ownership/lifetime: not retained or modified. A handle obtained from FindDateItemHandle() must still be valid (its collection not freed or mutated).

pDate

[Out] DATE_STRUCT *

Receives the year, month, and day of the item.

NULL: not allowed; the function returns FALSE.
Ownership: caller-allocated (for example, a stack variable). Nothing is allocated or retained by the library.
On failure: the contents of *pDate are not specified; do not use them.

Return Values

The function returns a BOOL, not an HRESULT. Test it directly (if (!GetDateItemDate(...))); do not use FAILED/SUCCEEDED.

Return value	Meaning
`TRUE`	`pDate` was populated successfully.
`FALSE`	`hDateItem` or `pDate` is NULL, or the item's internal FILETIME is zero/uninitialized (invalid).

Behavior and Operations

Validate arguments

→

Read item FILETIME

→

GetDateFromFiletime

→

Fill DATE_STRUCT

No error HRESULT is produced; the only distinction made is success versus failure. Because the call is marked _Check_return_, ignoring the result produces a code-analysis warning.

Remarks

Thread safety: the function works on the item only and takes no date log handle lock. A date item is immutable after creation, so concurrent reads of the same item are safe as long as the item itself is not freed meanwhile.
Handle lifetime: for handles that point into a collection, the item remains valid only as long as the collection is not freed or mutated. Take a copy with GetDateItemCopy() if you need it longer.
Time of day: only year, month, and day are returned; use GetDateItemFiletime() or GetDateItemSystemTime() for the full value.
Ordering: no ordering requirements; the item may be queried any number of times between creation and FreeDateItem().

Header note: the datelog.h reference lists GetDateItemDate as returning void, whereas this page (and the implementation documented here) defines it as returning BOOL. This page keeps the BOOL signature.

Sample Code


#include <Windows.h>
#include <stdio.h>
#include "datelog.h"

static BOOL MakeFiletime(WORD wYear, WORD wMonth, WORD wDay, PFILETIME pFiletime)
{
    SYSTEMTIME st = { 0 };

    st.wYear = wYear;
    st.wMonth = wMonth;
    st.wDay = wDay;
    return SystemTimeToFileTime(&st, pFiletime);
}

int main(void)
{
    HOLIDAYS_HANDLE  hHolidays = NULL;
    DATE_LOG_HANDLE  hDateLog = NULL;
    DATE_ITEM_HANDLE hItem = NULL;
    DATE_STRUCT      date = { 0 };
    FILETIME         ft = { 0 };
    HRESULT          hr = E_FAIL;
    int              exitCode = 1;

    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, NULL, &hHolidays, HandleIsForHolidays);
    if (FAILED(hr)) {
        printf("InitializeDateLogHandle [holidays] failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, hHolidays, &hDateLog, HandleIsForDatelog);
    if (FAILED(hr)) {
        printf("InitializeDateLogHandle [date log] failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    if (!MakeFiletime(2026, 10, 13, &ft)) {
        printf("SystemTimeToFileTime failed: %lu\n", GetLastError());
        goto cleanup;
    }

    hr = InitializeDateItem(hDateLog, &ft, NULL, &hItem);
    if (hr == ERR_DATE_IS_HOLIDAY) {
        printf("2026-10-13 is a weekend or market holiday.\n");
        goto cleanup;
    }
    if (FAILED(hr)) {
        printf("InitializeDateItem failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    /* GetDateItemDate returns BOOL, so test it directly rather than with FAILED. */
    if (!GetDateItemDate(hItem, &date)) {
        printf("GetDateItemDate failed (NULL argument or uninitialized item).\n");
        goto cleanup;
    }

    printf("Date item is %04d-%02u-%02u\n", (int)date.year, (unsigned)date.month, (unsigned)date.day);
    exitCode = 0;

cleanup:
    FreeDateItem(hItem);
    if (hDateLog != NULL) {
        hr = CloseDateLogHandle(hDateLog);
        if (FAILED(hr)) {
            printf("CloseDateLogHandle [date log] failed: 0x%08lX\n", (unsigned long)hr);
        }
    }
    if (hHolidays != NULL) {
        hr = CloseDateLogHandle(hHolidays);
        if (FAILED(hr)) {
            printf("CloseDateLogHandle [holidays] failed: 0x%08lX\n", (unsigned long)hr);
        }
    }
    return exitCode;
}