CloseDateLogHandle

Overview

CloseDateLogHandle releases a DATE_LOG_HANDLE, DATE_RANGE_HANDLE, or HOLIDAYS_HANDLE previously obtained from InitializeDateLogHandle or DuplicateDateLogHandle. Because multiple handles may share one underlying context (via duplication), the function uses a reference-counting model: each call releases exactly one handle, and the shared context (the date log core, the holidays handle, and any ODBC connections) is freed only when the last handle referencing it is closed.

Purpose

Provides deterministic, thread-safe teardown of date log, range, and holidays handles, ensuring that shared resources (mutexes, critical sections, ODBC connection lists, and the date item array) are released exactly once, even when handles are duplicated and closed concurrently from multiple threads.

Key Features

• Reference-counted context teardown — duplicated handles may be closed independently and in any order
• Refuses to close a handle that is currently locked/in-use (returns HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE_STATE))
• Frees all ODBC connections (and their underlying statements) owned by the context when the last reference is released
• Recursively closes the associated holidays handle when the last reference of a date log/range context is released

Function Signature

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

Calling Convention

Standard C calling convention with SAL annotations for parameter validation and return value inspection. The function is declared in datelog.h.

Parameters

Return Values

Success Cases

The handle was released; if it was the last reference to its context, the shared context was freed as well.

Error Cases

hDateLogHandle is NULL.

Timed out (5 seconds) waiting to acquire the handle’s own mutex.

The handle’s mutex was abandoned by another thread.

The internal lock state or context pointer is invalid/NULL.

The handle is currently locked/in-use by another thread (lock-state fields are non-zero).

Always test the result with FAILED()/SUCCEEDED(). The documentation does not specify whether a handle remains valid after a failing return, so do not reuse it.

Behavior and Operations

Execution Flow

Reference Counting

Each shared DATE_CONTEXT tracks uiHandles, which is incremented by DuplicateDateLogHandle and decremented here. Only when the count reaches zero are the date log core, ODBC connection internals, and holidays handle actually freed.

ODBC Cleanup

If the context owns ODBC connection internals (pConnInternals), every connection node is flushed from its internal SLIST and each underlying ODBC_CONNECTION_HANDLE is released via FreeOdbcConnectionContext() before the connection list header itself is freed. Connections created with ConnectDateLogHandleToOdbcDatabase are therefore closed automatically; no separate disconnect call is required.

Resource Cleanup

Performed regardless of the success/failure of the context-free step:

• Frees the handle’s own file context (if present)
• Closes the handle’s own mutex
• Frees the handle’s lock-state structure
• Frees the handle structure itself

Remarks

Thread Safety

The function acquires the handle’s mutex and then the shared context’s mutex, so closing duplicated handles from different threads is safe. It must not be called while the handle is locked by ValidateAndLockDateLogHandle(); doing so returns HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE_STATE). The call must also not race with other calls that use the same handle: once you have called CloseDateLogHandle on a handle, no thread may use it.

Handle Lifetime and Reference Counting

• InitializeDateLogHandle creates a new context with a reference count of one.
• DuplicateDateLogHandle adds one reference per duplicate; every duplicate must be closed with this function.
• Handles may be closed in any order. Closing the original handle does not invalidate its duplicates, because the shared context lives until the last reference is gone.
• A holidays handle passed to InitializeDateLogHandle is duplicated internally; the caller still owns, and must close, its own holidays handle.

Sample Code

The following example creates a holidays handle and a date log, duplicates the date log, and then closes every handle it obtained, checking each result.

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

int main(void)
{
    HOLIDAYS_HANDLE hHolidays = NULL;
    DATE_LOG_HANDLE hDateLog  = NULL;
    DATE_LOG_HANDLE hWorker   = NULL;
    HRESULT         hr        = E_FAIL;
    int             rc        = 1;

    /* Holidays handle. Populate it with your market holiday data (see
       LoadDateLogHandle) before building date logs; that step is application specific. */
    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, NULL, &hHolidays, HandleIsForHolidays);
    if (FAILED(hr)) {
        printf("InitializeDateLogHandle failed for holidays: 0x%08lX\n", (unsigned long)hr);
        return 1;
    }

    /* hHolidays is duplicated internally by InitializeDateLogHandle, so the
       caller keeps (and must close) its own reference. */
    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, hHolidays, &hDateLog, HandleIsForDatelog);
    if (FAILED(hr)) {
        printf("InitializeDateLogHandle failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup_holidays;
    }

    /* A duplicate shares the same context; the reference count is now 2. */
    hr = DuplicateDateLogHandle(hDateLog, &hWorker);
    if (FAILED(hr)) {
        printf("DuplicateDateLogHandle failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup_log;
    }

    /* Closing the duplicate only decrements the count; hDateLog stays usable. */
    hr = CloseDateLogHandle(hWorker);
    hWorker = NULL;
    if (FAILED(hr)) {
        printf("CloseDateLogHandle failed for duplicate: 0x%08lX\n", (unsigned long)hr);
        goto cleanup_log;
    }

    rc = 0;

cleanup_log:
    /* Closing the last handle referencing the context frees the shared context. */
    hr = CloseDateLogHandle(hDateLog);
    hDateLog = NULL;
    if (FAILED(hr)) {
        printf("CloseDateLogHandle failed: 0x%08lX\n", (unsigned long)hr);
        rc = 1;
    }

cleanup_holidays:
    hr = CloseDateLogHandle(hHolidays);
    hHolidays = NULL;
    if (FAILED(hr)) {
        printf("CloseDateLogHandle failed for holidays: 0x%08lX\n", (unsigned long)hr);
        rc = 1;
    }
    return rc;
}

See Also

• InitializeDateLogHandle — creates a date log, range, or holidays handle
• DuplicateDateLogHandle — creates an additional handle sharing the same context
• IsValidDateLogHandle — validates a handle before use
• ConnectDateLogHandleToOdbcDatabase — ODBC connections are released when the handle is closed
• FreeDateItem — releases standalone date items
• date_error_h — error code reference