ODBC_CONNECT_PARAMS Structure Documentation

Overview

ODBC_CONNECT_PARAMS is a structure that encapsulates ODBC (Open Database Connectivity) connection parameters and configuration options for connecting to a database server. It provides a convenient way to configure and manage multiple connection settings through a unified interface.

This structure is designed to work exclusively with the mdts_date library's ODBC integration features. The public view of this structure serves as an interface, while the library maintains the actual implementation details in an internal extended structure.

ODBC_CONNECT_PARAMS instances must be created exclusively through InitializeOdbcConnectParams() and must be freed with FreeOdbcConnectParams(). Never allocate this structure directly on the stack or with malloc().

Structure Definition

The ODBC_CONNECT_PARAMS structure (public view) is defined in datelog.h as follows:


typedef struct _ODBC_CONNECT_PARAMS {
    PODBC_PARAM_ENTRY     ParamList;      /* List of ODBC connection parameters */
    DWORD                 ParamCount;     /* Number of parameters in the list */
    DWORD                 MaxParamCount;  /* Maximum capacity of parameter list */
    ODBC_TRISTATE_FIELD   Trusted_Connection;  /* Trusted_Connection tri-state */
    ODBC_TRISTATE_FIELD   Encrypt;             /* Encrypt tri-state */
    ODBC_TRISTATE_FIELD   MARS_Connection;    /* MARS_Connection tri-state */
    ODBC_TRISTATE_FIELD   ColumnEncryption;   /* ColumnEncryption tri-state */
    HRESULT (*AddParam)(struct _ODBC_CONNECT_PARAMS *pParams, LPCSTR pszKey, LPCSTR pszValue);
    HRESULT (*ClearParams)(struct _ODBC_CONNECT_PARAMS *pParams);
} ODBC_CONNECT_PARAMS, *PODBC_CONNECT_PARAMS;

The actual internal implementation includes additional fields beyond what is exposed in this public definition. The public structure is always the first member of a larger internal structure maintained by the library. This design allows for backward compatibility and extensibility.

Structure Members

ParamList PODBC_PARAM_ENTRY

A pointer to the first element of an array of ODBC parameter entries. Each entry contains a key-value pair for an ODBC connection parameter.

ParamCount DWORD

The number of parameters currently stored in the parameter list. This count is maintained internally and updated when parameters are added.

MaxParamCount DWORD

The maximum number of parameters that can be stored in the current parameter list allocation. When ParamCount reaches MaxParamCount, the list is dynamically resized.

Trusted_Connection ODBC_TRISTATE_FIELD

Tri-state field for the Trusted_Connection ODBC keyword. Valid values are ODBC_UNSPECIFIED, ODBC_TRUE, or ODBC_FALSE.

Encrypt ODBC_TRISTATE_FIELD

Tri-state field for the Encrypt ODBC keyword, controlling whether connection encryption is required, optional, or not specified.

MARS_Connection ODBC_TRISTATE_FIELD

Tri-state field for the MARS_Connection (Multiple Active Result Sets) ODBC keyword.

ColumnEncryption ODBC_TRISTATE_FIELD

Tri-state field for the ColumnEncryption ODBC keyword, controlling column-level encryption settings.

AddParam Function pointer

Function pointer for adding a parameter to the connection. This is initialized to point to AddOdbcParamter() when the structure is created.

ClearParams Function pointer

Function pointer for clearing all parameters from the connection. This is initialized to point to an internal clearing function when the structure is created.

Tri-State Field Values

The boolean-like fields in ODBC_CONNECT_PARAMS use tri-state values to distinguish between explicit settings and defaults:

Value	Meaning	ODBC Behavior
`ODBC_UNSPECIFIED`	Not explicitly set	Uses ODBC driver's default behavior
`ODBC_TRUE`	Explicitly enabled	Feature is enabled in connection string
`ODBC_FALSE`	Explicitly disabled	Feature is disabled in connection string

Remarks

ODBC_CONNECT_PARAMS must be created through InitializeOdbcConnectParams(), which properly initializes the structure and internal allocations.
All tri-state fields are initialized to ODBC_UNSPECIFIED by default, allowing the ODBC driver to use its default behavior.
Parameters are added to the structure using the AddParam function pointer (typically AddOdbcParamter()).
The structure maintains an internal state that is hidden from the public interface for data protection and future extensibility.
Memory allocated for ODBC_CONNECT_PARAMS must be freed exclusively with FreeOdbcConnectParams().
The connection parameters list is dynamically managed and automatically resized as needed when new parameters are added.

Never declare an ODBC_CONNECT_PARAMS on the stack or allocate it with malloc(sizeof(ODBC_CONNECT_PARAMS)). This will allocate insufficient memory and cause heap corruption when AddParam() is called.

Usage Patterns

Creating and Configuring Connection Parameters


PODBC_CONNECT_PARAMS pParams = NULL;
HRESULT hr = E_FAIL;

/* Step 1: Initialize the parameters structure */
hr = InitializeOdbcConnectParams(&pParams);
if (FAILED(hr)) {
    printf("Failed to initialize ODBC connection parameters.\n");
    return hr;
}

/* Step 2: Add connection parameters */
hr = pParams->AddParam(pParams, "Driver", "{ODBC Driver 17 for SQL Server}");
if (FAILED(hr)) {
    printf("Failed to add Driver parameter.\n");
    FreeOdbcConnectParams(&pParams);
    return hr;
}

hr = pParams->AddParam(pParams, "Server", "localhost\\SQLEXPRESS");
hr = pParams->AddParam(pParams, "Database", "MyDatabase");
hr = pParams->AddParam(pParams, "UID", "sa");
hr = pParams->AddParam(pParams, "PWD", "Password123");

/* Step 3: Set tri-state properties */
pParams->Encrypt = ODBC_TRUE;
pParams->MARS_Connection = ODBC_TRUE;
pParams->Trusted_Connection = ODBC_FALSE;

/* Step 4: Use the parameters to connect a date log */
/* ... call ConnectDateLogHandleToOdbcDatabase() ... */

/* Step 5: Clean up */
FreeOdbcConnectParams(&pParams);

Sample Code

Complete Example: Setting Up ODBC Connection Parameters


#include "datelog.h"
#include 

int main(void)
{
    HRESULT hr = S_OK;
    PODBC_CONNECT_PARAMS pParams = NULL;

    /* Create a new ODBC connection parameters structure */
    hr = InitializeOdbcConnectParams(&pParams);
    if (FAILED(hr)) {
        printf("InitializeOdbcConnectParams failed with HRESULT 0x%08lx\n", hr);
        return 1;
    }

    printf("ODBC_CONNECT_PARAMS created successfully.\n");
    printf("Initial state:\n");
    printf("  ParamCount: %lu\n", pParams->ParamCount);
    printf("  MaxParamCount: %lu\n", pParams->MaxParamCount);
    printf("  Trusted_Connection: %d\n", pParams->Trusted_Connection);
    printf("  Encrypt: %d\n", pParams->Encrypt);

    /* Add some connection parameters */
    printf("\nAdding connection parameters...\n");
    
    if (pParams->AddParam != NULL) {
        pParams->AddParam(pParams, "Driver", "{ODBC Driver 17 for SQL Server}");
        printf("  Added Driver parameter. ParamCount: %lu\n", pParams->ParamCount);
        
        pParams->AddParam(pParams, "Server", "localhost");
        printf("  Added Server parameter. ParamCount: %lu\n", pParams->ParamCount);
        
        pParams->AddParam(pParams, "Database", "TestDB");
        printf("  Added Database parameter. ParamCount: %lu\n", pParams->ParamCount);
    }

    /* Set connection properties */
    printf("\nSetting connection properties...\n");
    pParams->Encrypt = ODBC_TRUE;
    pParams->MARS_Connection = ODBC_TRUE;
    pParams->Trusted_Connection = ODBC_TRUE;
    printf("  Encrypt: %d (ODBC_TRUE)\n", pParams->Encrypt);
    printf("  MARS_Connection: %d (ODBC_TRUE)\n", pParams->MARS_Connection);
    printf("  Trusted_Connection: %d (ODBC_TRUE)\n", pParams->Trusted_Connection);

    /* The parameters are now ready to be used with date log ODBC functions */
    printf("\nODBC_CONNECT_PARAMS is ready for database connection.\n");

    /* Clean up */
    hr = FreeOdbcConnectParams(&pParams);
    if (FAILED(hr)) {
        printf("FreeOdbcConnectParams failed with HRESULT 0x%08lx\n", hr);
        return 1;
    }

    printf("ODBC_CONNECT_PARAMS cleaned up successfully.\n");
    return 0;
}