GetDateItemNumber Function Documentation

Overview

GetDateItemNumber returns the dwDateNumber field of the given date item, which represents the item's position (ordinal number) within the owning date log core.

Purpose

Lets callers learn where a date item sits inside a date log without accessing internal structures. Items that live inside a date log are obtained with lookup functions such as FindDateItemHandle.

Key Features

Takes a single date item handle and returns a DWORD (declared unsigned int in datelog.h).
Annotated _Success_(return > 0): a positive value means a number was obtained.
Does not modify the item.

Function Signature


DWORD _Success_(return > 0) GetDateItemNumber(
    _In_ DATE_ITEM_HANDLE hDateItem
);

Parameters

hDateItem

[In] DATE_ITEM_HANDLE

The date item to query. NULL is tolerated and results in a return value of 0.

The handle is only read. Ownership is unchanged: standalone items remain the caller's responsibility (FreeDateItem), while items stored inside a date log are owned by that log and must not be freed individually.

Return Values

Value	Meaning
`> 0`	The date item's ordinal number.
`0`	`hDateItem` is NULL. Per the `_Success_(return > 0)` annotation, 0 is not a success value; treat it as "no number available".

This function returns a number, not an HRESULT. No error codes from date_error_h are returned directly. ERR_DATEITEM_BAD_NUMBER describes a corrupted sequential numbering inside a collection and is reported by other operations.

Remarks

Thread Safety

No locking is described for this accessor. If the date item belongs to a date log that other threads modify (for example through LoadDateLogHandle or MergeDateLogHandle), obtain a separate handle per thread with DuplicateDateLogHandle and look items up through that handle.

Ownership and Lifetime

The number is returned by value. The date item must remain valid for the duration of the call.

Related Functions

InitializeDateItem – creates standalone items.
FindDateItemHandle – locates an item stored in a date collection.
GetDateItemHandleGap – number of market days between two items.
GetDateCollectionLength – number of items in a collection.

The DATE_ITEM page lists a DateNumber member described as an OLE date (a double); this page and the header describe the value returned here as an integer ordinal. Use the return value of this function as documented here.

Sample Code


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

/* Builds a FILETIME for midnight (UTC) of the given calendar date. */
static BOOL MakeFiletime(WORD wYear, WORD wMonth, WORD wDay, FILETIME *pFileTime)
{
    SYSTEMTIME st = { 0 };

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

int main(void)
{
    HRESULT hr = E_FAIL;
    HOLIDAYS_HANDLE hHolidays = NULL;
    DATE_LOG_HANDLE hDateLog = NULL;
    DATE_ITEM_HANDLE hDateItem = NULL;
    DATE_ITEM_HANDLE hFound = NULL;
    FILETIME ft = { 0 };
    DWORD number = 0;
    int exitCode = 1;

    /* A holidays handle is created with HandleIsForHolidays; hHolidays must be NULL for that type. */
    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, NULL, &hHolidays, HandleIsForHolidays);
    if (FAILED(hr)) {
        printf("Holidays handle creation failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    /* The date log duplicates hHolidays internally; the caller still owns hHolidays. */
    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, hHolidays, &hDateLog, HandleIsForDatelog);
    if (FAILED(hr)) {
        printf("Date log creation 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, &hDateItem);
    if (FAILED(hr)) {
        printf("InitializeDateItem failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    /* A return value of 0 means no number is available for this item. */
    number = GetDateItemNumber(hDateItem);
    if (number > 0) {
        printf("Standalone item number: %lu\n", number);
    } else {
        printf("Standalone item has no ordinal number.\n");
    }

    /* Look the date up in the date log; items stored in the log are owned by the log. */
    hFound = FindDateItemHandle(hDateLog, NULL, &ft, NULL, NULL);
    if (hFound != NULL) {
        number = GetDateItemNumber(hFound);
        printf("Item number inside the date log: %lu (of %lu items)\n",
               number, GetDateCollectionLength(hDateLog));
    } else {
        printf("The date is not present in the date log yet.\n");
    }

    exitCode = 0;

cleanup:
    if (hDateItem != NULL) {
        FreeDateItem(hDateItem);
    }
    if (hDateLog != NULL) {
        CloseDateLogHandle(hDateLog);
    }
    if (hHolidays != NULL) {
        CloseDateLogHandle(hHolidays);
    }
    return exitCode;
}