DateLogHandleHasChanged Function Documentation

Overview

DateLogHandleHasChanged queries whether a date log collection has been modified since its creation or last reset. This function is commonly used to determine if the underlying date log file needs to be persisted to disk or if the collection has been updated with new dates or merged data.

Purpose

This function enables applications to:

Track state changes in date collections across operations
Determine when file persistence is necessary
Optimize I/O by avoiding unnecessary file writes
Support transactional patterns with change detection

Key Characteristics

Simple boolean query operation (no side effects)
Lightweight; no mutex or synchronization overhead beyond handle validation
Returns state set by LoadDateLogHandle(), MergeDateLogHandle(), or GenerateDateItemRangeCore()
Thread-safe read of cached state (via shared context)

Function Signature

BOOL _Check_return_ DateLogHandleHasChanged(
    _In_ DATE_COLLECTION_HANDLE hDateLogHandle
);

Calling Convention

Standard C calling convention. The function is exported via MDTSAPI macro.

SAL Annotations

_Check_return_ - Return value must be inspected by caller
_In_ - Input parameter; must not be modified
DATE_COLLECTION_HANDLE - Generic handle type (accepts DATE_LOG_HANDLE, DATE_RANGE_HANDLE, or HOLIDAYS_HANDLE)

Parameters

hDateLogHandle

[In] DATE_COLLECTION_HANDLE

Handle to the date collection to query for changes.

Can be a DATE_LOG_HANDLE obtained from InitializeDateLogHandle()
Can be a DATE_RANGE_HANDLE created via NewDateLogHandle()
Can be a HOLIDAYS_HANDLE from GetDateLogHolidayHandle()
Should represent a valid collection (recommended: validate before calling)
If NULL or invalid, function safely returns FALSE

Return Values

Return Value Semantics

TRUE - The date collection has been modified since creation or last operation

New dates were added via LoadDateLogHandle()
Dates were generated via GenerateDateItemRangeCore()
Data was merged via MergeDateLogHandle()
File persistence is recommended if changes should be saved

FALSE Cases

FALSE - No changes detected

Returned when:

Collection is in original state (no operations performed)
hDateLogHandle is NULL
Handle is invalid or corrupted
Internal context structure is NULL

Return Value Checking Pattern


// Recommended usage pattern
DATE_LOG_HANDLE hLog = /* ... */;

if (DateLogHandleHasChanged(hLog)) {
    // Collection has been modified
    printf("Date log has changes that need persistence\n");
    
    // Example: Save to file
    // hr = SaveDateLogToFile(hLog, "mylog.dat");
} else {
    // No changes detected
    printf("Date log is unchanged; no save needed\n");
}

Behavior and State Management

State Tracking Diagram

Initialize Handle

→

bHasChanged = FALSE

Load/Generate/Merge

→

bHasChanged = TRUE

Query Status

→

Return TRUE/FALSE

When bHasChanged is Set to TRUE

The internal bHasChanged flag is set to TRUE by:

LoadDateLogHandle(): After successfully parsing a date log file or generating a date range
MergeDateLogHandle(): After successfully merging source dates into destination
GenerateDateItemRangeCore(): After generating dates within a specified range

Initial State

When a new date collection handle is created via InitializeDateLogHandle(), the bHasChanged flag is initialized to FALSE. The handle is considered "clean" until data is loaded or modified.

State Persistence

The changed state is cached in the shared context (DATE_CONTEXT)
All duplicates created via DuplicateDateLogHandle() share the same state
State reflects the collective changes to the underlying date collection
No explicit reset function; state is tied to collection lifetime

Handle Validation

This function performs minimal validation:

Checks if hDateLogHandle is NULL (returns FALSE if so)
Checks if internal context is NULL (defensive check, returns FALSE)
Does NOT verify magic numbers or full handle integrity (for performance)
Assumes handle has been pre-validated by caller

Recommendation: Consider calling IsValidDateLogHandle() before DateLogHandleHasChanged() if the handle comes from untrusted sources or if handle validity is uncertain.

Usage Examples

Example 1: Check After Loading File


// Load a date log from file
DATE_LOG_HANDLE hLog = NULL;
HRESULT hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, hHolidays, &hLog, HandleIsForDatelog);
if (SUCCEEDED(hr)) {
    hr = LoadDateLogHandle(pFileInfo, NULL, NULL, hLog, NULL, 0);
    
    if (SUCCEEDED(hr)) {
        // Check if loading resulted in changes
        if (DateLogHandleHasChanged(hLog)) {
            printf("Loaded %d dates from file\n", GetDateCollectionLength(hLog));
        }
    }
    
    CloseDateLogHandle(hLog);
}

Example 2: Determine File Persistence Strategy


// Optimize file I/O based on change status
void OptimizeDateLogPersistence(DATE_LOG_HANDLE hLog, const char* filepath)
{
    if (DateLogHandleHasChanged(hLog)) {
        printf("Changes detected; writing to %s...\n", filepath);
        // TODO: Implement file write
        // HRESULT hr = WriteDateLogToFile(hLog, filepath);
    } else {
        printf("No changes; skipping file write for %s\n", filepath);
    }
}

// Usage
OptimizeDateLogPersistence(hMyLog, "market_dates.bin");

Example 3: Track Changes Across Operations


// Monitor state through multiple operations
DATE_LOG_HANDLE hLog = /* initialized */;

printf("Initial state: %s\n", DateLogHandleHasChanged(hLog) ? "Changed" : "Clean");
// Output: Clean

// Load data
hr = LoadDateLogHandle(pFileInfo, NULL, NULL, hLog, NULL, 0);
printf("After load: %s\n", DateLogHandleHasChanged(hLog) ? "Changed" : "Clean");
// Output: Changed

// Merge additional data
hr = MergeDateLogHandle(hLog, hSourceRange, DATE_RANGE_MERGE_FAVOR_SOURCE);
printf("After merge: %s\n", DateLogHandleHasChanged(hLog) ? "Changed" : "Clean");
// Output: Changed

Example 4: Transactional Pattern with Change Detection


// Implement a "save-only-if-changed" pattern
HRESULT UpdateAndSaveDateLog(DATE_LOG_HANDLE hLog, PFILE_CONTEXT pNewData)
{
    HRESULT hr = S_OK;
    
    // Record initial state
    BOOL bInitiallyChanged = DateLogHandleHasChanged(hLog);
    
    // Perform updates
    hr = LoadDateLogHandle(pNewData, NULL, NULL, hLog, NULL, 0);
    if (FAILED(hr)) {
        return hr;
    }
    
    // Only save if changes occurred during this operation
    if (!bInitiallyChanged && DateLogHandleHasChanged(hLog)) {
        printf("New changes detected; persisting to disk...\n");
        // hr = PersistDateLogToDisk(hLog);
    }
    
    return hr;
}

Remarks and Best Practices

Thread Safety

This function is thread-safe for read operations:

The bHasChanged flag is read from the shared context
Multiple threads can call this function concurrently on the same handle
No mutex is acquired; the read is atomic at the implementation level
Note: State may change between the call and when the value is used

Performance Considerations

O(1) operation: Simple pointer dereference; no searching or locking
No file I/O: Purely in-memory state query
Minimal validation: Only NULL checks; intentionally lightweight
Safe to call frequently (e.g., in loops) without performance penalty

Common Pitfalls

Pitfall	Impact	Mitigation
Not checking return value	Silent logic errors in persistence logic	Always use if statement or ternary operator
Ignoring NULL returns	Incorrect change detection with invalid handles	Validate handle before calling; function returns FALSE safely
Race conditions (multi-threaded)	State may change between check and use	Use atomic operations or synchronize caller's logic
Assuming state is reset	Stale state prevents re-saves	No reset function; create new handle if needed

API Contract Notes

Important:

The function parameter is typed as DATE_COLLECTION_HANDLE (generic void pointer)
Accepts DATE_LOG_HANDLE, DATE_RANGE_HANDLE, or HOLIDAYS_HANDLE
All three types share the same underlying context structure
Return value indicates whether ANY changes occurred to the collection

Integration with Other Functions

LoadDateLogHandle(): Sets bHasChanged = TRUE on success
MergeDateLogHandle(): Sets bHasChanged = TRUE after merge
InitializeDateLogHandle(): Initializes bHasChanged = FALSE
DuplicateDateLogHandle(): Shares bHasChanged with source handle