DateLog Public API Reference

Overview

datelog.h is the public API header for the MDTS Date Log library. It provides comprehensive functionality for managing date collections, handling market trading day validation, and performing date range operations with support for holidays and weekends.

Key Capabilities

• Date Log Management: Create, duplicate, and close date log handles
• Date Item Operations: Create, search, navigate, and analyze date items
• Range Operations: Load, merge, and convert date ranges
• Market Day Validation: Automatically validate weekends and holidays
• Thread Safety: Full mutex-based synchronization for concurrent access
• File I/O: Persistent storage with region locking and backup/restore
• ODBC Integration: SQL bulk insert/fetch support for backend operations

Header File Location

Dependencies

• <Windows.h> — Windows API
• <sqltypes.h> — SQL type definitions
• mdts_io_.h — File I/O library
• date_item.h — Date item internal definitions

Required Includes

#ifndef _WINDOWS_
#error Microsoft header file <Windows.h> is required for this library.
#endif

#if WINVER < _WIN32_WINNT_WIN10
#error Windows 10 or later is required for this library.
#endif

#include <Windows.h>
#include <sqltypes.h>
#include "mdts_io_.h"
#include "date_item.h"

Type Definitions & Opaque Handles

Handle Types

All handles in this library are opaque pointers, providing type safety through distinct typedefs:

Enumerations

DateHandleType

Specifies the type of handle to create when initializing a date log:

typedef enum {
    HandleIsForDatelog = 1,     // Complete date log collection
    HandleIsForRange,           // Date range subset
    HandleIsForHolidays         // Market holidays collection
} DateHandleType;

DateGapSpec

Controls how gap calculations include or exclude date boundaries:

typedef enum {
    InclusiveDateGap,           // Both start and end dates included in gap
    ExclusiveDateGap            // Only dates between start and end included
} DateGapSpec;

Constants & Macros

Sizing Constants

Merge Flags

Alignment Macros

#define ALIGN_DOWN(x, align) ((x) / (align) * (align))
#define ALIGN_UP(x, align) (((x) + (align) - 1) / (align) * (align))

Date Log Handle Management

Exported Functions

• InitializeDateLogHandle
• DuplicateDateLogHandle
• CloseDateLogHandle

InitializeDateLogHandle

Creates and initializes a new date log handle.

DuplicateDateLogHandle

Creates a new handle referencing the same shared context for concurrent access.

CloseDateLogHandle

Frees resources and closes a handle.

Date Item Creation & Initialization

Exported Functions

• InitializeDateItem
• GetMostRecentCallendarMarketDate
• FreeDateItem

InitializeDateItem

Creates and validates a new date item from FILETIME or LARGE_INTEGER.

GetMostRecentCallendarMarketDate

Returns the most recent market trading day from the system calendar.

FreeDateItem

Frees resources allocated for a date item.

Date Log Loading & Merging

Exported Functions

• LoadDateLogHandle
• MergeDateLogHandle
• ConvertToDateLogHandle

LoadDateLogHandle

Generates or extends a date collection with dates from file or range.

MergeDateLogHandle

Merges a source date range into a destination date log with conflict resolution.

ConvertToDateLogHandle

Converts and verifies a date range handle to a date log handle.

Date Item Navigation & Lookup

Exported Functions

• FindDateItemByHandle
• FindDateItemByGuid
• FindDateItemByDate
• GetDateLogFirstDate
• GetDateLogLastDate
• GetNextDateItemFromHandle
• GetPreviousDateItemFromHandle

FindDateItemByHandle

Finds a date item by exact handle match.

FindDateItemByGuid

Finds a date item by UUID.

FindDateItemByDate

Finds a date item by date value.

Date Item Analysis & Comparison

Exported Functions

• GetDateItemGap
• IsDateItemMarketHoliday
• IsFiletimeMarketHoliday
• IsDateCoveredByDateLog
• IsDateFutureDate
• IsNextMarketDay
• CompareDateItem
• GetDateItemId
• GetDateItemDate
• GetDateItemFiletime
• GetDateItemNumber

GetDateItemGap

Calculates market trading days between two dates.

IsDateItemMarketHoliday

Checks if a date item is a weekend or market holiday.

IsFiletimeMarketHoliday

Checks if a FILETIME is a weekend or market holiday.

Handle Validation & Inspection

Exported Functions

• IsValidDateLogHandle
• IsValidHolidaysHandle
• DateLogHasChanged

IsValidDateLogHandle

Validates a DATE_LOG_HANDLE, DATE_RANGE_HANDLE, or HOLIDAYS_HANDLE.

IsValidHolidaysHandle

Validates a HOLIDAYS_HANDLE specifically.

DateLogHasChanged

Checks if a date log has been modified since creation.

Collection Metadata & Inspection

Exported Functions

• GetDateCollectionLength
• GetDateCollectionMaximumLength
• GetDateLogHolidayHandle

GetDateCollectionLength

Returns the current number of date items in a collection.

GetDateCollectionMaximumLength

Returns the maximum capacity of a date collection.

GetDateLogHolidayHandle

Retrieves the holidays handle associated with a date log.

Configuration & Localization

Exported Functions

• SetDatelogLocale
• SetDateLogHandleOdbcBulkInsertPort
• GetDateLogEncryptionPassData

SetDatelogLocale

Sets the locale for all date log operations.

SetDateLogHandleOdbcBulkInsertPort

Configures ODBC bulk insert port for SQL backend operations.

GetDateLogEncryptionPassData

Retrieves encryption key material for date item backend decryption.

Full Header File

Below is the complete styled public API header file with all exported functions, type definitions, and constants properly organized and documented.

    /* ============================================================================
    * MDTS Date Log Library - Public API Header
    * ============================================================================
    *
    * Copyright (c) 2026 Benjamin R. Pena
    * All rights reserved.
    *
    * This source code is proprietary and confidential. Unauthorized copying,
    * modification, distribution, or any form of use without explicit permission
    * from the copyright holder is strictly prohibited.
    *
    * This code is provided "as is," without warranties or guarantees of any kind,
    * express or implied, including but not limited to warranties of merchantability
    * or fitness for a particular purpose. The copyright holder shall not be held
    * liable for any damages arising from the use of this software.
    *
    * For permissions or inquiries, please contact: admin@mdts.app
    * ============================================================================
    */

    #pragma once

    #ifndef _WINDOWS_
    #error Microsoft header file <Windows.h> is required for this library.
    #endif

    #if WINVER < _WIN32_WINNT_WIN10
    #error Windows 10 or later is required for this library.
    #endif

    /* ============================================================================
    * INCLUDES
    * ============================================================================ */

    #include <Windows.h>
    #include <sqltypes.h>
    #include "mdts_io_.h"
    #include "date_item.h"

    #ifdef MDTS_EXPORTS
    #define MDTSAPI __declspec(dllexport)
    #else
    #define MDTSAPI  __declspec(dllimport)
    #endif // !MDTS_EXPORTS

    /* ============================================================================
    * TYPE DEFINITIONS & OPAQUE HANDLES
    * ============================================================================ */

    typedef void* DATE_LOG_HANDLE;
    typedef void* DATE_RANGE_HANDLE;
    typedef void* HOLIDAYS_HANDLE;
    typedef void* DATE_COLLECTION_HANDLE;
    typedef void* DATE_ITEM_HANDLE;


    /* ============================================================================
    * CONSTANTS & MACROS
    * ============================================================================ */

    #define DATE_LOG_MAX 0x591C8
    #define DAY_IN_MILLISECONDS 0xC92A69C000

    #define DATE_RANGE_MERGE_FAVOR_DEST 4
    #define DATE_RANGE_MERGE_FAVOR_SOURCE 8
    #define DATE_RANGE_MERGE_RESTORE_ON_FAILURE 16

    /* ============================================================================
    * ENUMERATIONS
    * ============================================================================ */

    typedef enum {
        HandleIsForDatelog = 1,
        HandleIsForRange,
        HandleIsForHolidays
    } DateHandleType;

    typedef enum {
        InclusiveDateGap,
        ExclusiveDateGap
    } DateGapSpec;

    /* ============================================================================
    * FUNCTION DECLARATIONS - HANDLE MANAGEMENT
    * ============================================================================ */

    MDTSAPI
    HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return))
    InitializeDateLogHandle(
    _In_opt_ PSECURITY_ATTRIBUTES pSecAttr,
    _In_opt_ const DWORD dwMaximumLength,
    _In_opt_ HOLIDAYS_HANDLE hHolidays,
    _Out_ DATE_LOG_HANDLE* hDateLogHandle,
    _In_ DateHandleType HandleType
    );

    MDTSAPI
    HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return))
    DuplicateDateLogHandle(
    _In_ DATE_LOG_HANDLE hSourceHandle,
    _Out_ DATE_LOG_HANDLE* lpTargetHandle
    );

    MDTSAPI
    HRESULT _Success_(SUCCEEDED(return))
    CloseDateLogHandle(
    _In_ _Post_invalid_ DATE_LOG_HANDLE hDateLogHandle
    );


    /* ============================================================================
    * FUNCTION DECLARATIONS - DATE ITEM CREATION
    * ============================================================================ */

    MDTSAPI
    HRESULT _Must_inspect_result_ _Success_(hDateItem != NULL && SUCCEEDED(return))
    InitializeDateItem(
    _In_ _Pre_valid_ DATE_LOG_HANDLE hDateLogHandle,
    _In_opt_ PFILETIME pFileTime,
    _In_opt_ PLARGE_INTEGER pLargeInteger,
    _Out_ DATE_ITEM_HANDLE* hDateItem
    );

    MDTSAPI
    void FreeDateItem(
    _In_ _Post_invalid_ DATE_ITEM_HANDLE hDateItem
    );


    /* ============================================================================
    * FUNCTION DECLARATIONS - LOADING & MERGING
    * ============================================================================ */

    MDTSAPI
    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
    );

    MDTSAPI
    HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return))
    MergeDateLogHandle(
    _Inout_ _Pre_valid_ DATE_LOG_HANDLE hDestDateLog,
    _In_ __readonly _Pre_valid_ DATE_RANGE_HANDLE hSourceDateLog,
    _In_ DWORD dwFlags
    );

    MDTSAPI
    HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return))
    ConvertToDateLogHandle(
    _Inout_ _Pre_valid_ DATE_RANGE_HANDLE hDateRangeHandle,
    _In_opt_ DATE_ITEM_HANDLE hLastDate
    );


    /* ============================================================================
    * FUNCTION DECLARATIONS - NAVIGATION & LOOKUP
    * ============================================================================ */

    MDTSAPI
    DATE_ITEM_HANDLE _Check_return_ _Success_(return != NULL)
    FindDateItemByHandle(
    _In_ _Pre_valid_ DATE_COLLECTION_HANDLE hDateCollection,
    _In_ CONST DATE_ITEM_HANDLE hDateItem
    );

    MDTSAPI
    DATE_ITEM_HANDLE _Check_return_ _Success_(return != NULL)
    FindDateItemByGuid(
    _In_ _Pre_valid_ DATE_COLLECTION_HANDLE hDateCollection,
    _In_ GUID* rfDateId
    );

    MDTSAPI
    DATE_ITEM_HANDLE _Check_return_ _Success_(return != NULL)
    FindDateItemByDate(
    _In_ _Pre_valid_ DATE_COLLECTION_HANDLE hDateCollection,
    _In_ DATE_STRUCT* pDate
    );

    /* ============================================================================
    * FUNCTION DECLARATIONS - ANALYSIS & COMPARISON
    * ============================================================================ */

    MDTSAPI
    signed int GetDateItemGap(
    _In_ _Pre_valid_ DATE_LOG_HANDLE hDateLogHandle,
    _In_ DATE_ITEM_HANDLE hStartDate,
    _In_ DATE_ITEM_HANDLE hEndDate,
    _In_ DateGapSpec DateGapType
    );

    MDTSAPI
    int CompareDateItem(
    _In_ DATE_ITEM_HANDLE pDateItem1,
    _In_ DATE_ITEM_HANDLE pDateItem2
    );

    MDTSAPI
    void GetDateItemId(
    _In_ DATE_ITEM_HANDLE hDateItem,
    _Out_ GUID* rfDateId
    );

    MDTSAPI
    void GetDateItemDate(
    _In_ DATE_ITEM_HANDLE hDateItem,
    _Out_ DATE_STRUCT* pDate
    );

    MDTSAPI
    unsigned int _Success_(return > 0)
    GetDateItemNumber(
    _In_ DATE_ITEM_HANDLE hDateItem
    );

    MDTSAPI
    void _Success_(pFiletime != NULL)
    GetDateItemFiletime(
    _In_ DATE_ITEM_HANDLE hDateItem,
    _Out_ PFILETIME pFiletime
    );

    MDTSAPI
    DATE_ITEM_HANDLE _Check_return_ _Success_(return != NULL)
    GetDateItemCopy(
    _In_ DATE_ITEM_HANDLE hDateItem
    );


    /* ============================================================================
    * FUNCTION DECLARATIONS - VALIDATION
    * ============================================================================ */

    MDTSAPI
    BOOL DateLogHasChanged(
    _In_ _Pre_valid_ DATE_LOG_HANDLE hDateLogHandle
    );

    MDTSAPI
    BOOL _Check_return_ IsValidDateLogHandle(
    _In_  DATE_COLLECTION_HANDLE hDateLogHandle
    );

    /* ============================================================================
    * FUNCTION DECLARATIONS - METADATA & INSPECTION
    * ============================================================================ */

    MDTSAPI
    DWORD GetDateCollectionLength(
    _In_ _Pre_valid_ DATE_COLLECTION_HANDLE hDateCollection
    );

    MDTSAPI
    DWORD GetDateCollectionMaximumLength(
    _In_ _Pre_valid_ DATE_COLLECTION_HANDLE hDateCollection
    );

    MDTSAPI
    HOLIDAYS_HANDLE _Check_return_ _Success_(return != NULL)
    GetDateLogHolidayHandle(
    _In_ _Pre_valid_ DATE_LOG_HANDLE hDatelogHandle
    );

    /* ============================================================================
    * FUNCTION DECLARATIONS - CONFIGURATION & LOCALIZATION
    * ============================================================================ */

    MDTSAPI
    HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return))
    SetDatelogLocale(
    _In_ PUNICODE_STRING pLocale
    );

    MDTSAPI
    HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return))
    SetDateLogHandleOdbcBulkInsertPort(
    _In_ _Pre_valid_ DATE_LOG_HANDLE hDateLogHandle,
    _Inout_updates_(sizeof(DWORD)) PSQL_DATE_BULK pSQLOdbcPort
    );

    #endif /* _DATELOG_H_ */