LoadDateLogHandle

Overview

LoadDateLogHandle is the primary entry point for populating a DATE_LOG_HANDLE, DATE_RANGE_HANDLE or HOLIDAYS_HANDLE with date items. It can do so in three ways:

• by parsing an existing physical file (the file argument);
• by generating a fresh contiguous range between hStartDate and hEndDate when no file is supplied;
• by auto-extending an already-loaded date log up to the most recent market date (DATE_LOG_AUTO_UPDATE_FLAG).

The behavior depends on the type of the handle that is passed in. The handle type is determined when the handle is created with InitializeDateLogHandle (HandleIsForDatelog, HandleIsForRange or HandleIsForHolidays).

Key Features

• Parses existing date-log files via multithreaded chunked parsing, optionally reporting progress through a DATE_COLLECTION_PROGRESS structure.
• Can auto-extend a log to the current date via DATE_LOG_AUTO_UPDATE_FLAG.
• Generates and merges a range when the parsed file’s last date lags the target end date.
• Supports failure-restore of the prior core via DATE_RANGE_MERGE_RESTORE_ON_FAILURE.
• Computes and stores a SHA-256 file hash for integrity verification.

Function Signature

HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return)) LoadDateLogHandle(
    _In_opt_  PFILE_INFO                pFileInfo,
    _In_opt_  DATE_ITEM_HANDLE          hStartDate,
    _In_opt_  DATE_ITEM_HANDLE          hEndDate,
    _In_      DATE_LOG_HANDLE           hDateLogHandle,
    _In_opt_  PDATE_COLLECTION_PROGRESS pProgData,
    _In_      DWORD                     dwFlags
);

The declaration follows datelog.h, where the first parameter is PFILE_INFO pFileInfo. The file type is declared in mdts_io_.h, which is not documented in this help set. The function takes exactly six arguments, in this order.

Calling Convention

Standard C calling convention with SAL annotations for parameter validation and return value inspection.

Parameters

Return Values

Use FAILED/SUCCEEDED to test the result; the value must be inspected (_Must_inspect_result_). The codes ERR_* are defined in date_error.h. On failure, the error date item (if any) is captured for later retrieval through GetDateLogHandleErrorInfo().

Behavior and Operations

On failure, the old core is restored (if DATE_RANGE_MERGE_RESTORE_ON_FAILURE was set and a prior core existed) and the error date item (if any) is captured via GetDateLogCoreErrorItemInfo() for later retrieval through GetDateLogHandleErrorInfo().

Remarks

Thread Safety

The handle is locked for the duration of the load and unlocked before returning, so concurrent operations on the same shared context are serialized. Do not call other functions on the same handle from another thread and expect them to run in parallel with a load; use DuplicateDateLogHandle to give each thread its own handle onto the shared context.

Handle Lifetime and Ownership

• The target handle is populated in place and stays open. Handles that share a context are reference counted; the context is freed only when the last handle is closed with CloseDateLogHandle.
• Date item arguments are inputs only. Free the items you created with FreeDateItem after the call, on success and on failure.
• A date log or range created with a holidays handle uses a duplicate of that holidays handle; close your own holidays handle separately.

Ordering and Related Functions

• Create the handle with InitializeDateLogHandle first. A date log or range needs a populated holidays handle, so load the holidays handle (HandleIsForHolidays) before loading a log that depends on it.
• Start and end dates are created with InitializeDateItem, which rejects holiday dates with ERR_DATE_IS_HOLIDAY.
• After a successful load, GetDateCollectionLength reports the number of items, and IsDateLogHandleUpToDate tells whether the log reaches the most recent market date.
• To combine ranges, see MergeDateLogHandle; to promote a merged range to a date log, see ConvertDateLogHandle.
• A date log is limited to DATE_LOG_MAX (0x591C8 = 370,120) items (datelog.h).

See Also

• InitializeDateLogHandle
• InitializeDateItem
• MergeDateLogHandle
• ConvertDateLogHandle
• IsDateLogHandleUpToDate
• GetDateCollectionLength
• DuplicateDateLogHandle
• FreeDateItem
• CloseDateLogHandle
• DATE_COLLECTION_PROGRESS
• datelog.h – public header reference
• date_error.h – error code reference

Sample Code

The sample generates a range without a file: it loads a holidays handle for 2025-01-02 through 2025-03-31, creates a date log that uses it, loads the same range into the log, and prints the number of items. It then shows a documented failure by trying to load an inverted range into a date range handle (ERR_DATE_EARLIER_BASE). To parse an existing file instead, pass a PFILE_INFO as the first argument (created by the mdts_io_.h file library, which is not covered here); add DATE_LOG_AUTO_UPDATE_FLAG to extend a file-backed log to the most recent market date. All date items and handles are released on every path.

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

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

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

int main(void)
{
    int exitCode = 1;
    HRESULT hr = S_OK;
    FILETIME ftFirst = { 0 };
    FILETIME ftLast = { 0 };
    HOLIDAYS_HANDLE hHolidays = NULL;
    DATE_LOG_HANDLE hDateLog = NULL;
    DATE_LOG_HANDLE hRange = NULL;
    DATE_ITEM_HANDLE hFirst = NULL;
    DATE_ITEM_HANDLE hLast = NULL;
    DWORD dwLength = 0;

    if (!MakeFileTime(2025, 1, 2, &ftFirst) || !MakeFileTime(2025, 3, 31, &ftLast)) {
        printf("Invalid calendar date.\n");
        return 1;
    }

    /* 1. A holidays handle is generated first; the log and range reference it. */
    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, NULL, &hHolidays, HandleIsForHolidays);
    if (FAILED(hr)) {
        printf("Creating the holidays handle failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    hr = InitializeDateItem(hHolidays, &ftFirst, NULL, &hFirst);
    if (FAILED(hr)) {
        printf("Creating the first date item failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }
    hr = InitializeDateItem(hHolidays, &ftLast, NULL, &hLast);
    if (FAILED(hr)) {
        printf("Creating the last date item failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    /* No file: generate the range [first, last]. Progress reporting applies to file parsing only. */
    hr = LoadDateLogHandle(NULL, hFirst, hLast, hHolidays, NULL, 0);
    if (FAILED(hr)) {
        printf("Loading the holidays handle failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    /* 2. Create the date log that uses the holidays handle and generate its dates. */
    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, hHolidays, &hDateLog, HandleIsForDatelog);
    if (FAILED(hr)) {
        printf("Creating the date log failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    hr = LoadDateLogHandle(NULL, hFirst, hLast, hDateLog, NULL, 0);
    if (FAILED(hr)) {
        printf("Loading the date log failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    dwLength = GetDateCollectionLength(hDateLog);
    if (dwLength > DATE_LOG_MAX) {
        printf("GetDateCollectionLength reported a failure.\n");
        goto cleanup;
    }
    printf("The date log now holds %lu date items.\n", (unsigned long)dwLength);

    /* 3. Demonstrate a documented failure: the start date must be earlier than the end date. */
    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, hHolidays, &hRange, HandleIsForRange);
    if (FAILED(hr)) {
        printf("Creating the range failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    hr = LoadDateLogHandle(NULL, hLast, hFirst, hRange, NULL, 0);
    if (hr == ERR_DATE_EARLIER_BASE) {
        printf("Rejected as expected: the start date is not earlier than the end date.\n");
    } else if (FAILED(hr)) {
        printf("Loading the range failed: 0x%08lX\n", (unsigned long)hr);
    } else {
        printf("Unexpected success loading the inverted range.\n");
    }

    exitCode = 0;

cleanup:
    FreeDateItem(hLast);
    FreeDateItem(hFirst);
    if (hRange != NULL) {
        (void)CloseDateLogHandle(hRange);
    }
    if (hDateLog != NULL) {
        (void)CloseDateLogHandle(hDateLog);
    }
    if (hHolidays != NULL) {
        (void)CloseDateLogHandle(hHolidays);
    }
    return exitCode;
}