Vývoj aplikací v C a C++ s ovladačem ODBC

Verze: 18.7.1.1
Datum: 7. září 2026

Pro volání ODBC API z C nebo C++ zahrňte sql.h, sqlext.h, a sqltypes.h, poté propojte s importní knihovnou správce ovladačů. Chcete-li používat rozšíření pro SQL Server, která ovladač Microsoft ODBC Driver for SQL Server přidává nad rámec standardu ODBC, zahrňte také msodbcsql.h a zařaďte jej za základní hlavičky ODBC.

Platí na: Microsoft ODBC Driver 18 pro SQL Server na Windows, Linux a macOS. Verze 17 používá stejný název hlavičky s instalační cestou 170 a názvem knihovny msodbcsql17 .

Hlavičky a knihovny

Platforma poskytuje základní hlavičkové soubory ODBC a správce ovladačů, nikoli balíček ovladačů. Na Windows jsou dodávány ve Windows SDK. Na Linuxu a macOS jsou dodávány v balíčku unixODBC. SDK ovladače poskytuje pouze msodbcsql.h a knihovnu pro import pomocí hromadného kopírování.

To, co nazýváš	Headers	Windows	Linux	macOS
ODBC API	sql.h, sqlext.h, sqltypes.h	odbc32.lib	-lodbc	-lodbc
ODBC API, vstupní body pro Unicode	Přidejte sqlucode.h	odbc32.lib	-lodbc	-lodbc
API instalačního programu ODBC	Přidejte odbcinst.h	odbccp32.lib	-lodbcinst	-lodbcinst
Rozšíření ovladačů pro SQL Server	Přidejte msodbcsql.h	Žádná další knihovna	Žádná další knihovna	Žádná další knihovna
Funkce hromadného kopírování (bcp_*)	Přidejte msodbcsql.h	msodbcsql18.lib	-lmsodbcsql-18	-lmsodbcsql.18

Název odkazu pro hromadné kopírování se liší podle platformy, protože názvy souborů se liší. V Linuxu se -lmsodbcsql-18 vyhodnocuje přes symbolický odkaz libmsodbcsql-18.so v /usr/lib, které linker už prohledává, takže -L nepotřebujete. V systému macOS se ovladač dodává jako libmsodbcsql.18.dylib, kterému odpovídá -lmsodbcsql.18, ale knihovní adresář Homebrew není na počítačích Apple Silicon ve výchozím vyhledávacím umístění. Přidejte -L$(brew --prefix)/lib, když propojíte funkce hromadného kopírování.

Pouze funkce hromadného kopírování vyžadují vlastní knihovnu ovladače. Atributy spojení, atributy příkazů, atributy sloupců a identifikátory typů SQL Server jsou makry a definice typů, takže jejich zahrnutí msodbcsql.h stačí.

Instalační API je samostatná knihovna od ODBC API. Volání funkce, například SQLGetPrivateProfileString bez -lodbcinst, na Linuxu nebo macOS selže při linkování s chybou „undefined reference“, nikoli při kompilaci.

Pro instalaci vývojového balíčku unixODBC, který poskytuje hlavní hlavičky na Linuxu a macOS, viz Install the unixODBC driver manager.

Zahrňte wchar.h před msodbcsql.h v C kódu na Linuxu a macOS

Verze msodbcsql.h pro Linux a macOS deklarují rozhraní poskytovatele Always Encrypted keystore pomocí wchar_t, ale neobsahují hlavičku, která by tento typ definovala. V C++ je klíčové slovo wchar_t , takže překladové jednotky v C++ se budují bez potřeby dalších hlaviček. V jazyce C je wchar_t typedef, takže je potřeba do překladové jednotky C nejprve zahrnout <wchar.h>:

#include <wchar.h>

Pokud nezahrnete <wchar.h>, kompilátor hlásí chyby msodbcsql.h zevnitř unknown type name 'wchar_t'. Přidání include je na Windows neškodné, proto ho přidávejte do sdíleného zdroje, místo abyste ho umisťovali za platformový ochranný systém.

Zařaďte msodbcsql.h za základní hlavičky ODBC

Vše, co msodbcsql.h definuje nad rámec maker názvu ovladače, je uvnitř bloku #ifdef ODBCVER a sql.h je to, co definuje ODBCVER. Pokud zahrnete msodbcsql.h jako první, předprocesor přeskočí celý blok a hlavička nepřispěje k ničemu. Kompilátor žádné varování nevydá.

/* Correct order. */
#ifdef _WIN32
#include <windows.h>
#endif

#include <wchar.h>
#include <sql.h>
#include <sqlext.h>
#include <sqltypes.h>
#include <msodbcsql.h>

Zahrnutí msodbcsql.h před sql.h blokem nechává vše uvnitř bloku ODBCVER nedefinované. Kompilátor hlásí chybu v místě použití, nikoli u direktivy include:

order-wrong.c(7): error C2065: 'SQL_COPT_SS_BCP': undeclared identifier

Na Windows musíte zahrnout windows.h před hlavičky ODBC. Kopie sqltypes.h a sql.h v sadě Windows SDK používají typy systému Windows, jako jsou DWORD a LONG. msodbcsql.hzabaluje své struktury SQL Serveru do pshpack8.h a poppack.h. Bez windows.h, build selže přímo v hlavičkách SDK.

Kde jsou soubory SDK nainstalovány

Platforma	msodbcsql.h	Knihovna hromadných kopií
Windows	%ProgramFiles%\Microsoft SQL Server\Client SDK\ODBC\180\SDK\Include	%ProgramFiles%\Microsoft SQL Server\Client SDK\ODBC\180\SDK\Lib\<architecture>\msodbcsql18.lib
Linux	/opt/microsoft/msodbcsql18/include	/opt/microsoft/msodbcsql18/lib64, se symbolickým odkazem /usr/lib/libmsodbcsql-18.so
macOS	$(brew --prefix msodbcsql18)/include/msodbcsql18	$(brew --prefix)/lib/libmsodbcsql.18.dylib

Ve Windows složka Lib obsahuje podsložku pro každou procesorovou architekturu, kterou instalátor na stroj umístil, například x64, x86, nebo arm64. Přidejte složku Include do cesty include kompilátoru a podsložku architecture do cesty k knihovně linkeru.

Na Linuxu je sdílený objekt verzován, pojmenovaný jako libmsodbcsql-18.6.so.2.1, a nenese žádné SONAME. Balíček nainstaluje /usr/lib/libmsodbcsql-18.so, který na něj odkazuje, takže se -lmsodbcsql-18 přeloží i bez volby -L. Odkazujte přes tento symlink místo pojmenovávání verze souboru, aby aktualizace ovladače nerozbila váš build.

V systému macOS se Homebrew instaluje do vlastního prefixu, který je /opt/homebrew na počítačích Apple Silicon a /usr/local na Intelu. Oba prefixy jsou symbolické odkazy do verzovaného adresáře Cellar. Použijte brew --prefix msodbcsql18 a brew --prefix unixodbc ve svém build skriptu místo toho, abyste je natvrdo zakódovali.

Číslo na cestě odpovídá verzi hlavního pohonu. Verze 17 se ve Windows instaluje do ...\ODBC\170\SDK\ a v Linuxu do /opt/microsoft/msodbcsql17/ a její importní knihovna je msodbcsql17.lib.

Pro kompletní seznam souborů podle jednotlivých platforem viz Systémové požadavky, instalace a soubory ovladačů (Windows),Nainstalovat ovladač ODBC na Linux a Nainstalovat ovladač ODBC na macOS.

Ověřte si své nastavení stavby

Tento program kompiluje proti hlavičkám, odkazuje na správce ovladačů a uvádí ovladače, které správce ovladačů vidí. Nepřipojuje se, takže odděluje problém s buildem nebo registrací od problému se sítí nebo přihlašováním.

#include <stdio.h>
#include <wchar.h>

#ifdef _WIN32
#include <windows.h>
#endif

#include <sql.h>
#include <sqlext.h>
#include <sqltypes.h>
#include <msodbcsql.h>

static void PrintDiagnostics(SQLSMALLINT handleType, SQLHANDLE handle)
{
    SQLCHAR state[6];
    SQLINTEGER native;
    SQLCHAR message[SQL_MAX_MESSAGE_LENGTH];
    SQLSMALLINT length;

    for (SQLSMALLINT record = 1;
         SQL_SUCCEEDED(SQLGetDiagRec(handleType, handle, record, state, &native,
                                     message, sizeof(message), &length));
         ++record)
    {
        fprintf(stderr, "  [%s] (%ld) %s\n", state, (long)native, message);
    }
}

int main(void)
{
    SQLHENV environment = SQL_NULL_HENV;
    SQLRETURN rc = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &environment);

    if (!SQL_SUCCEEDED(rc))
    {
        fprintf(stderr, "SQLAllocHandle for the environment failed.\n");
        return 1;
    }

    rc = SQLSetEnvAttr(environment, SQL_ATTR_ODBC_VERSION,
                       (SQLPOINTER)SQL_OV_ODBC3_80, 0);
    if (!SQL_SUCCEEDED(rc))
    {
        fprintf(stderr, "SQLSetEnvAttr for SQL_OV_ODBC3_80 failed.\n");
        PrintDiagnostics(SQL_HANDLE_ENV, environment);
        SQLFreeHandle(SQL_HANDLE_ENV, environment);
        return 1;
    }

    printf("Driver name from msodbcsql.h: %s\n", SQLODBC_DRIVER_NAME);
    printf("Installed drivers:\n");

    SQLCHAR description[256];
    SQLSMALLINT descriptionLength = 0;
    SQLUSMALLINT direction = SQL_FETCH_FIRST;

    while (SQL_SUCCEEDED(SQLDrivers(environment, direction,
                                    description, sizeof(description), &descriptionLength,
                                    NULL, 0, NULL)))
    {
        printf("  %s\n", description);
        direction = SQL_FETCH_NEXT;
    }

    SQLFreeHandle(SQL_HANDLE_ENV, environment);
    return 0;
}

Sestavte ho jako program s úzkými znaky. SQLODBC_DRIVER_NAME se rozvine na široký řetězec, když je definováno UNICODE nebo _UNICODE, což printf s %s nemůže přijmout.

Windows

cl /W4 /I "%ProgramFiles%\Microsoft SQL Server\Client SDK\ODBC\180\SDK\Include" odbc-build-check.c /link odbc32.lib

Linux

gcc -Wall -o odbc-build-check odbc-build-check.c \
    -I/opt/microsoft/msodbcsql18/include -lodbc

macOS

clang -Wall -o odbc-build-check odbc-build-check.c \
    -I"$(brew --prefix unixodbc)/include" \
    -I"$(brew --prefix msodbcsql18)/include/msodbcsql18" \
    -L"$(brew --prefix unixodbc)/lib" -lodbc

V systému Windows hlásí /W4 dvě C4201: nonstandard extension used: nameless struct/union varování z kopie sqlext.h ze sady Windows SDK. Tato varování pocházejí z hlavičky SDK, ne z vašeho kódu, a sestavení je úspěšné.

První řádek uvádí název ovladače zkompilovaný do vašeho binárního souboru. Zbytek je vlastní seznam správce ovladačů, takže ovladač, který byste tam očekávali, ale není tam, představuje problém s registrací, nikoli problém sestavení. Váš seznam se bude lišit a zahrnuje všechny nainstalované ODBC ovladače, nejen ty pro SQL Server:

Driver name from msodbcsql.h: ODBC Driver 18 for SQL Server
Installed drivers:
  SQL Server
  ODBC Driver 17 for SQL Server
  ODBC Driver 18 for SQL Server
  Microsoft Access Driver (*.mdb, *.accdb)
  Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb)
  Microsoft Access Text Driver (*.txt, *.csv)
  Microsoft Access dBASE Driver (*.dbf, *.ndx, *.mdx)

Sestavte připojovací řetězec z SQLODBC_DRIVER_NAME, nikoli z řetězcového literálu. Makro odkazuje na hlavičkový soubor, vůči němuž jste kompilovali, takže po aktualizaci sady SDK se název ovladače aktualizuje na jednom místě.

Co msodbcsql.h přidává do ODBC API

msodbcsql.hrozšiřuje standardní ODBC API o specifika SQL Server. Každá rodina zabírá souvislý číselný rozsah počítaný od základní konstanty. Rozsahy nejsou mezi rodinami jedinečné, takže funkce, které předáte hodnotu, je to, co je od sebe rozlišuje.

Rodina	Základní konstanta	Value
Atributy spojení pro SQLSetConnectAttr	SQL_COPT_SS_BASE	1200
Atributy příkazu pro SQLSetStmtAttr	SQL_SOPT_SS_BASE	1225
Sloupcové atributy pro SQLColAttribute	SQL_CA_SS_BASE	1200
Typy informací pro SQLGetInfo	SQL_INFO_SS_FIRST	1199
Diagnostická pole pro SQLGetDiagField	SQL_DIAG_SS_BASE	-1150
Diagnostické dynamické funkční kódy	SQL_DIAG_DFC_SS_BASE	-200

Hlavička také uvádí:

• Autentizační atributy, včetně SQL_COPT_SS_AUTHENTICATION a SQL_COPT_SS_ACCESS_TOKEN, které nesou nastavení Microsoft Entra ID a přístupové tokeny.
• Identifikátory typů SQL v rozsahu -150 až -199 pro typy SQL Serveru, které ODBC nedefinuje: SQL_SS_VARIANT, SQL_SS_UDT, SQL_SS_XML, SQL_SS_TABLE, SQL_SS_TIME2, SQL_SS_TIMESTAMPOFFSET a SQL_SS_VECTOR. Tyto určují typ SQL, takže je předáváte tam, kde ODBC očekává typ SQL, například jako argument ParameterType funkce SQLBindParameter.
• Tři odpovídající typy C pro stranu bufferu: SQL_C_SS_TIME2, SQL_C_SS_TIMESTAMPOFFSET, a SQL_C_SS_VECTOR. Ostatní typy serveru SQL Server se vážou na standardní typ ODBC C, například SQL_C_BINARY nebo SQL_C_WCHAR, takže nemají odpovídající protějšek SQL_C_SS_*.
• Struktury, ke kterým se vážou typy SQL_C_SS_*: SQL_SS_TIME2_STRUCT, SQL_SS_TIMESTAMPOFFSET_STRUCT a SQL_SS_VECTOR_STRUCT.
• Hromadně kopírovat prototypy a makra, včetně bcp_init, bcp_bind, bcp_sendrow, bcp_batch a bcp_done. Možnosti BCP_ENCRYPT_OFF, BCP_ENCRYPT_ON, a BCP_ENCRYPT_STRICT možnosti jsou pouze v hlavičce Windows.

Každá platforma má svou vlastní kopii msodbcsql.h, a ne všechny deklarují stejné symboly. Struktura SQLPERF a atributy připojení k výkonu, které ji vyplňují, jako SQL_COPT_SS_PERF_DATA a SQL_COPT_SS_PERF_QUERY, jsou pouze v hlavičce Windows. Hlavičky Linuxu a macOS je nedeklarují a ovladač na těchto platformách nesbírá data o výkonu. Viz Programátorské pokyny (Linux a macOS).

Pro klíčová slova připojovací řetězec, kterým tyto atributy odpovídají, viz DSN a připojovací řetězec klíčová slova a atributy. Pro nastavení Microsoft Entra ID viz Použít Microsoft Entra ID s ovladačem ODBC. Pro typ vektoru viz Vektorový datový typ.

Vyberte mezi asynchronním spouštěním a vlákny

Některé ODBC funkce mohou běžet synchronně nebo asynchronně. V synchronním režimu ovladač nevrátí řízení, dokud server neodpoví. V asynchronním režimu ovladač ihned vrátí SQL_STILL_EXECUTING a aplikace opakuje stejné volání se stejnými argumenty, dokud nezíská jiný návratový kód. Jakýkoli jiný návratový kód, včetně SQL_ERROR, znamená, že operace byla dokončena.

Asynchronní režim má dvě formy a jednu z nich používáte. Zavolejte SQLGetInfo s SQL_ASYNC_MODE, abyste zjistili, kterou z nich ovladač podporuje. Vrátí se SQL_AM_STATEMENT , pokud ovladač podporuje řízení podle jednotlivých příkazů, SQL_AM_CONNECTION pokud se nastavení vztahuje na celé připojení, nebo SQL_AM_NONE pokud ovladač vůbec nevykonává funkce asynchronně.

Příkazová forma zapíná asynchronní režim pro jeden deskriptor příkazu. Každé ostatní příkazy na spojení zůstávají synchronní, takže můžete spustit oba typy současně:

SQLSetStmtAttr(hStmt, SQL_ATTR_ASYNC_ENABLE,
               (SQLPOINTER)SQL_ASYNC_ENABLE_ON, SQL_IS_INTEGER);

Pokud SQL_ASYNC_MODE vrátí SQL_AM_CONNECTION, atribut příkazu je pouze pro čtení a toto volání vrátí SQL_ERROR s hodnotou SQLSTATE HYC00. Použijte místo toho formulář pro připojení.

Formulář spojení se zapne asynchronně pro každý příkazový handle, který na daném spojení alokujete. Zda ovlivňuje i již existující handle, je definováno ovladačem, takže ho nastavte před alokací jakýchkoli příkazů:

SQLSetConnectAttr(hDbc, SQL_ATTR_ASYNC_ENABLE,
                  (SQLPOINTER)SQL_ASYNC_ENABLE_ON, SQL_IS_INTEGER);

Volání vrátí SQL_ERROR s hodnotou SQLSTATE HY010, pokud je pro příkaz daného připojení stále asynchronně spouštěna nějaká funkce. Otevřený kurzor sám o sobě volání neblokuje. Předáním SQL_ASYNC_ENABLE_OFF se všechny příkazy v daném připojení přepnou zpět do synchronního režimu.

Chcete-li zjistit, kolik asynchronních příkazů ovladač podporuje současně na jednom spojení, volejte SQLGetInfo s .SQL_MAX_ASYNC_CONCURRENT_STATEMENTS Microsoft ODBC Driver 18 pro SQL Server vrací hodnotu 1, takže počítejte s jednou nevyřízenou asynchronní operací na jedno připojení a pokud potřebujete více, otevřete další připojení nebo používejte vlákna. Viz Asynchronní provádění (metoda dotazování).

Vlákna jsou dalším způsobem, jak provádět několik operací souběžně. ODBC vyžaduje, aby ovladače na vícevláknových operačních systémech byly bezpečné pro vlákna, takže vlákno může provést blokující volání ODBC, zatímco ostatní vlákna stále pracují. Tím se vyhnete dotazovací smyčce a opakovaným voláním funkcí, které asynchronní režim vyžaduje. Každému vláknu přiřaďte vlastní identifikátor příkazu. Ovladač pravděpodobně serializuje dvě vlákna, která používají stejný handle současně, takže sdílení jednoho vás stojí souběžnost. Viz Multithreading. Preferujte vlákna pro nový kód a měřte si vlastní pracovní zátěž před převodem asynchronního kódu, který už funguje.

Na Windows správce ovladačů také podporuje metodu oznámení, která odstraňuje smyčku dotazování. Událost Win32 spojujete s handlem spojení nebo výpisu. Funkce stále okamžitě vrátí hodnotu SQL_STILL_EXECUTING a správce ovladačů signalizuje událost po dokončení operace. Dotazování je v tomto režimu zakázáno: opakované volání původní funkce vrátí SQL_ERROR s kódem SQLSTATE IM017. Místo toho zavolejte SQLCompleteAsync, abyste získali výsledek. To vyžaduje správce ovladačů verze ODBC 3.81 a novější verze, a ovladač to musí také podporovat. Zavolejte na číslo SQL_ASYNC_NOTIFICATION pomocí SQLGetInfo a zkontrolujte to. Vrácená hodnota závisí na verzi ODBC, kterou vaše aplikace deklaruje: při použití Microsoft ODBC Driver 18 pro SQL Server aplikace, která nastaví SQL_ATTR_ODBC_VERSION na SQL_ASYNC_NOTIFICATION_CAPABLE, obdrží SQL_OV_ODBC3_80, zatímco aplikace, která deklaruje SQL_OV_ODBC3, obdrží ze stejného ovladače SQL_ASYNC_NOTIFICATION_NOT_CAPABLE. Deklarujte SQL_OV_ODBC3_80 předtím, než alokujete připojení. Viz Asynchronní provádění (metoda oznámení) a vzorek metody oznámení.

Zrušit nevyřízenou operaci

SQLCancel zruší operaci, která stále běží na příkazovém handle. Zavolejte ji z jiného vlákna nebo z cyklu dotazování a předejte handle neukončeného volání.

Používejte SQLCancel jen na to. Chcete-li ukončit čtení sady výsledků, kterou už nechcete číst, zavolejte místo toho SQLCloseCursor nebo SQLMoreResults.

Migrace z sqlncli.h na msodbcsql.h

SQL Server Native Client je vyřazen, takže aplikace, které jej používají, by měly přejít na Microsoft ODBC Driver for SQL Server. API je stejné jako ODBC API, takže většina práce spočívá v přejmenování vstupů sestavení a názvu ovladače v připojovací řetězec.

Nativní klient SQL Serveru	Ovladač Microsoft ODBC 18 pro SQL Server
sqlncli.h	msodbcsql.h
sqlncli11.lib	msodbcsql18.lib
sqlncli11.dll	msodbcsql18.dll
Driver={SQL Server Native Client 11.0}	Driver={ODBC Driver 18 for SQL Server}
SQLNCLI_VER	SQLODBC_VER

Hlavička msodbcsql.h stále definuje SQLNCLI_* názvy makro, takže zdrojový kód, který je používá, se stále kompiluje. Tyto definice jsou chráněny #ifndef __sqlncli_h__, což znamená, že nemůžete zahrnout obě hlavičky do stejné translační jednotky. Odstraňte direktivu sqlncli.h include.

Dvě věci se nepřenášejí dál:

• Funkce distribuovaného API metadat dotazů, které vracejí seznamy propojených serverů a jejich katalogů, nejsou deklarovány v msodbcsql.h. Tyto byly specifické pro SQL Server Native Client.
• Verze 18 ve výchozím nastavení šifruje připojení a ověřuje serverový certifikát. Native Client ne. Connection string, který fungoval s Native Clientem, může při prvním připojení selhat, dokud neopravíte důvěryhodnost certifikátu nebo výslovně nenastavíte Encrypt. Viz Řešení problémů s šifrováním připojení.

Pro zbytek změn mezi verzí 17 a verzí 18 viz Hlavní rozdíly verzí.

Související obsah

• Připojte se k databázi a dotazujte ji pomocí C++
• DSN a klíčová slova a atributy připojovacího řetězce
• Programátorské pokyny (Linux a macOS)
• Referenční dokumentace programátora ODBC
• Ovladač Microsoft ODBC pro SQL Server