ODBC sürücüsüyle C ve C++ uygulamaları geliştirin

Sürüm: 18.7.1.1
Tarih: 7 Eylül 2026

ODBC API’sini C veya C++’tan çağırmak için sqlext.h, sqltypes.h ve sql.h dosyalarını dahil edin, ardından sürücü yöneticisinin içe aktarma kitaplığına bağlayın. Microsoft ODBC Driver for SQL Server'ın ODBC standardına ek olarak sunduğu SQL Server uzantılarını kullanmak için msodbcsql.h dosyasını da ekleyin ve bunu temel ODBC üst bilgi dosyalarından sonra ekleyin.

Şunlar için geçerlidir: Windows, Linux ve macOS üzerinde SQL Server için Microsoft ODBC Driver 18. Sürüm 17, msodbcsql17 kurulum yolu ve 170 kitaplık adıyla aynı üstbilgi adını kullanır.

Başlıklar ve kütüphaneler

Platform, çekirdek ODBC başlıklarını ve sürücü yöneticisini sağlar, sürücü paketini değil. Windows'ta ise Windows SDK ile gönderiliyor. Linux ve macOS'ta ise unixODBC geliştirme paketiyle birlikte geliyorlar. Sürücü SDK'sı yalnızca msodbcsql.h ve toplu kopya içe aktarma kütüphanesini içerir.

adlandırdığın şey Headers Windows Linux macOS
ODBC API'si sql.h, sqlext.h, sqltypes.h odbc32.lib -lodbc -lodbc
ODBC API, Unicode giriş noktaları sqlucode.h ekle odbc32.lib -lodbc -lodbc
ODBC Yükleyici API’si odbcinst.h ekle odbccp32.lib -lodbcinst -lodbcinst
SQL Server sürücü uzantıları msodbcsql.h ekle Ekstra kütüphane yok Ekstra kütüphane yok Ekstra kütüphane yok
Toplu kopya (bcp_*) fonksiyonları msodbcsql.h ekle msodbcsql18.lib -lmsodbcsql-18 -lmsodbcsql.18

Toplu kopyalama bağlantı adı, dosya adları farklı olduğu için platforma göre farklılık gösterir. Linux'ta -lmsodbcsql-18, bağlayıcının zaten aradığı /usr/lib içindeki bir libmsodbcsql-18.so sembolik bağlantısı üzerinden çözülür; bu yüzden -L öğesine ihtiyacınız yok. macOS'ta sürücü libmsodbcsql.18.dylib olarak gelir; bu, -lmsodbcsql.18 ile eşleşir, ancak Homebrew'in kitaplık dizini Apple Silicon'da varsayılan arama yolunda değildir. Toplu kopyalama işlevlerini bağlarken -L$(brew --prefix)/lib ekleyin.

Sadece toplu kopyalama fonksiyonları sürücünün kendi kütüphanesine ihtiyaç duyar. Bağlantı özellikleri, ifade nitelikleri, sütun özellikleri ve SQL Server tip tanımlayıcıları makrolar ve tür tanımlayıcılardır, bu yüzden dahil msodbcsql.h etmek yeterlidir.

Kurulumcu API, ODBC API'sinden ayrı bir kütüphanedir. Linux veya macOS'ta, SQLGetPrivateProfileString olmadan -lodbcinst gibi bir işlevi çağırmak, derleme zamanında değil, bağlama zamanında tanımlanmamış bir başvuru hatasıyla başarısız olur.

Linux ve macOS'ta çekirdek başlıkları sağlayan unixODBC geliştirme paketini kurmak için, unixODBC sürücü yöneticisini kur bölümüne bakınız.

Linux ve macOS'ta C koduna msodbcsql.h'den önce wchar.h'yi ekleyin

msodbcsql.h'ın Linux ve macOS sürümleri, Always Encrypted anahtar deposu sağlayıcı arabirimini wchar_t kullanarak bildirir, ancak bu türü tanımlayan bir üst bilgi dosyası içermezler. C++'da ise wchar_t anahtar kelimedir, yani C++ çeviri birimleri ekstra başlıklara ihtiyaç duymadan oluşturulur. C'de bir wchar_t tipdef olduğu için <wchar.h> önce C çeviri birimine dahil etmeniz gerekiyor:

#include <wchar.h>

Eğer <wchar.h> eklemezseniz, derleyici unknown type name 'wchar_t' içinden msodbcsql.h hataları bildirir. Windows’ta include ifadesini eklemenin bir sakıncası yoktur; bu yüzden onu platform koşullu derleme korumasının arkasına almak yerine paylaşılan kaynağa ekleyin.

Çekirdek ODBC başlıklarından sonra msodbcsql.h ekleyin

Sürücü adı makrolarının ötesinde msodbcsql.h’ın tanımladığı her şey bir #ifdef ODBCVER bloğunun içindedir ve sql.h, ODBCVER’ü tanımlayan şeydir. Önce eklerseniz msodbcsql.h , ön işlemci tüm bloğu atlar ve başlık hiçbir katkı sağlamaz. Derleyici uyarı vermiyor.

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

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

msodbcsql.h öğesinden önce sql.h öğesinin dahil edilmesi, ODBCVER bloğunun içindeki her şeyi tanımsız bırakır. Derleyici hatayı include noktasında değil, kullanım noktasında bildirir:

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

Windows'ta ise ODBC başlıklarının önüne girmeniz windows.h gerekir. DWORD ve LONG öğelerinin Windows SDK’daki kopyaları, sqltypes.h ve sql.h gibi Windows türlerini kullanır. msodbcsql.h, SQL Server yapılarını poppack.h ve pshpack8.h içine alır. windows.h olmadan, derleme doğrudan SDK başlıklarında başarısız olur.

SDK dosyalarının yüklendiği yer

Platform msodbcsql.h Toplu kopya kütüphanesi
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, bir /usr/lib/libmsodbcsql-18.so sembolik bağlantı ile
macOS $(brew --prefix msodbcsql18)/include/msodbcsql18 $(brew --prefix)/lib/libmsodbcsql.18.dylib

Windows'ta, klasör, Lib yükleyicinin makineye yerleştirdiği her işlemci mimarisi için bir alt klasör içerir; örneğinx64, , x86, veya arm64. Include klasörünü derleyicinin include arama yoluna ve mimari alt klasörünü bağlayıcının kitaplık yoluna ekleyin.

Linux'ta paylaşılan nesne sürümlüdür, adı libmsodbcsql-18.6.so.2.1 biçimindedir ve SONAME taşımaz. Paket, onu işaret eden /usr/lib/libmsodbcsql-18.so öğesini yükler; -L öğesinin -lmsodbcsql-18 seçeneği olmadan çözümlenmesini sağlayan da budur. Sürüm dosyasına isim vermek yerine o simlinkle bağlantı kur, böylece sürücü güncellemesi yapınızı bozmaz.

macOS'ta Homebrew kendi önekine yüklenir; bu önek Apple silicon'da /usr/local, Intel'de ise /opt/homebrew'dir. Her iki ön ek de sürümlendirilmiş Cellar dizinine işaret eden sembolik bağlantılardır. Derleme betiğinizde, bunlardan herhangi birini sabit olarak kodlamak yerine brew --prefix msodbcsql18 ve brew --prefix unixodbc kullanın.

Yoldaki sayı, ana sürücü versiyonunu takip eder. Sürüm 17, Windows'ta ...\ODBC\170\SDK\ konumuna ve Linux'ta msodbcsql17.lib konumuna yüklenir; içe aktarma kitaplığı ise /opt/microsoft/msodbcsql17/'dir.

Platform başına tam dosya envanteri için Sistem gereksinimleri, kurulum ve sürücü dosyaları (Windows), Linux'ta ODBC sürücüsünü yükle ve macOS'a ODBC sürücüsünü yükle bölümlerine bakabilirsiniz.

Yapı kurulumunuzu doğrulayın

Bu program, başlıklara karşı derler, sürücü yöneticisine bağlantılar verir ve sürücü yöneticisinin görebildiği sürücüleri listeler. Bağlanmıyor; bu da derleme veya kayıt sorununu ağ ya da kimlik bilgisi sorunundan ayırt etmeyi sağlar.

#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;
}

Bunu dar karakterli bir program olarak derle. UNICODE veya _UNICODE tanımlandığında SQLODBC_DRIVER_NAME, geniş karakterli bir dizeye genişler; printf ise bunu %s ile kabul edemez.

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

Windows'ta, /W4, Windows SDK kopyasında bulunan C4201: nonstandard extension used: nameless struct/union için iki sqlext.h uyarısı raporlar. Bu uyarılar kodunuzdan değil, SDK başlığından gelir ve derleme başarılı olur.

İlk satır, ikili dosyanıza derlenmiş olan sürücü adını belirtir. Geri kalanı sürücü yöneticisinin kendi listesidir, yani beklediğiniz ve görmediğiniz sürücü bir kayıt sorunudur, yapı sorunu değil. Listeniz farklı olacak ve sadece SQL Server sürücülerini değil, tüm kurulu ODBC sürücülerini içerir:

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)

Bağlantı dizesini bir dize sabitinden değil, SQLODBC_DRIVER_NAME öğesinden oluşturun. Makro, derleme yaptığınız başlık dosyasını izler; bu nedenle SDK’yı yükselttiğinizde sürücü adı tek bir yerde güncellenir.

msodbcsql.h'nin ODBC API'sine ne ekleyeceği

msodbcsql.hstandart ODBC API'sini SQL Server özellikleriyle genişletir. Her aile, temel sabitten sayılan bitişik bir sayısal aralığı kaplar. Aralıklar aileler arasında benzersiz değildir, bu yüzden değeri aktardığınız fonksiyon onları ayıran şeydir.

Aile Temel sabiti Value
SQLSetConnectAttr için bağlantı öznitelikleri SQL_COPT_SS_BASE 1200
SQLSetStmtAttr için deyim öznitelikleri SQL_SOPT_SS_BASE 1225
SQLColAttribute için sütun öznitelikleri SQL_CA_SS_BASE 1200
SQLGetInfo için bilgi türleri SQL_INFO_SS_FIRST 1199
SQLGetDiagField için tanılama alanları SQL_DIAG_SS_BASE -1150
Tanısal dinamik fonksiyon kodları SQL_DIAG_DFC_SS_BASE -200

Başlık ayrıca şöyle belirtir:

  • SQL_COPT_SS_ACCESS_TOKEN ve SQL_COPT_SS_AUTHENTICATION dahil olmak üzere, Microsoft Entra ID ayarlarını ve erişim belirteçlerini taşıyan kimlik doğrulama öznitelikleri.
  • ODBC'nin tanımlamadığı SQL Server tipler için -150 ile -199 aralığındaki SQL tür tanımlayıcıları: SQL_SS_VARIANT, SQL_SS_UDT, , SQL_SS_TIME2SQL_SS_TIMESTAMPOFFSETSQL_SS_XMLSQL_SS_TABLE, ve .SQL_SS_VECTOR Bunlar bir SQL türünü belirtir; bu nedenle, ODBC’nin bir SQL türü beklediği yerlerde, örneğin SQLBindParameter öğesinin ParameterType argümanı için bunları kullanırsınız.
  • Tampon tarafı için üç uyumlu C tipi: SQL_C_SS_TIME2, SQL_C_SS_TIMESTAMPOFFSET, ve SQL_C_SS_VECTOR. Diğer SQL Server türleri, örneğin SQL_C_WCHAR veya SQL_C_BINARY gibi standart bir ODBC C tipine bağlanır; bu nedenle SQL_C_SS_* karşılığı yoktur.
  • SQL_C_SS_* tiplerinin bağlandığı yapılar: SQL_SS_TIME2_STRUCT, SQL_SS_TIMESTAMPOFFSET_STRUCT ve SQL_SS_VECTOR_STRUCT.
  • bcp_bind, bcp_sendrow, bcp_batch, bcp_done ve bcp_init dahil olmak üzere prototipleri ve makroları toplu olarak kopyalayın. BCP_ENCRYPT_OFF, BCP_ENCRYPT_ON, ve BCP_ENCRYPT_STRICT seçenekler yalnızca Windows başlığında bulunur.

Her platform kendi kopyasını msodbcsql.hgönderiyor ve hepsi aynı sembolleri ilan etmiyor. Yapı SQLPERF ve onu dolduran performans bağlantı özellikleri, örneğin SQL_COPT_SS_PERF_DATA ve SQL_COPT_SS_PERF_QUERY, yalnızca Windows başlığında yer alır. Linux ve macOS başlıkları bunları bildirmiyor ve sürücü bu platformlarda performans verisi toplamıyor. Programlama yönergeleri (Linux ve macOS) bölümüne bakınız.

Bu özelliklerin karşılık verdiği bağlantı dizesi anahtar kelimeleri için DSN ve bağlantı dizesi anahtar kelimeler ve özellikler bölümlerine bakınız. Microsoft Entra ID kurulumu için bkz. ODBC sürücüsüyle Microsoft Entra ID kullanma. Vektör tipi için bkz. Vektör veri tipi.

Asenkron uygulama ile iş parçacıkları arasında seçim yapın

Bazı ODBC fonksiyonları hem eşzamanlı hem de asenkron olarak çalışabilir. Senkron modda, sürücü sunucu cevap verene kadar kontrolü geri getirmez. Asenkron modda, sürücü hemen geri SQL_STILL_EXECUTING döner ve uygulama aynı çağrıyı aynı argümanlarla tekrarlar, ta ki farklı bir dönüş kodu alana kadar. SQL_ERROR dahil diğer tüm dönüş kodları, işlemin tamamlandığı anlamına gelir.

Asenkron modun iki formu var ve bunlardan birini kullanıyorsunuz. Sürücünün hangisini desteklediğini öğrenmek için SQLGetInfo öğesini SQL_ASYNC_MODE ile çağırın. Sürücü ifade başına denetimi destekliyorsa SQL_AM_CONNECTION, ayar tüm bağlantı için geçerliyse SQL_AM_NONE veya sürücü işlevleri hiç eşzamansız çalıştırmıyorsa SQL_AM_STATEMENT döndürür.

İfade biçimi, bir ifade tanıtıcısı için asenkron modu etkinleştirir. Bağlantıdaki diğer tüm ifadeler senkronize kalır, böylece her iki türü aynı anda çalıştırabilirsiniz:

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

Eğer SQL_ASYNC_MODE dönerseSQL_AM_CONNECTION, ifade özniteliği yalnızca okunur ve bu çağrı SQLSTATE HYC00ile dönerSQL_ERROR. Bunun yerine bağlantı formunu kullanın.

Bağlantı formu, sonrasında o bağlantıya tahsis ettiğiniz her ifade adresi için asenkron modu açar. Bunun mevcut tutamaçları da etkileyip etkilemeyeceği sürücüye bağlıdır, bu yüzden herhangi bir komut oluşturmadan önce bunu ayarlayın:

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

Çağrı, bir fonksiyon o bağlantı için bir ifadede hâlâ asenkron olarak çalışıyorsa SQLSTATE HY010 ile dönerSQL_ERROR. Açık bir imleç tek başına çağrıyı engellemez. Pas yapmak, SQL_ASYNC_ENABLE_OFF bağlantıdaki tüm ifadeleri tekrar senkron moda getirir.

Tek bir bağlantıda sürücünün aynı anda kaç zaman uyumsuz ifadeyi desteklediğini öğrenmek için, SQL_MAX_ASYNC_CONCURRENT_STATEMENTS ile SQLGetInfo öğesini çağırın. Microsoft ODBC Driver 18 for SQL Server 1 gönderiyor, bu yüzden her bağlantı için bir asenkron işlem planlayın ve daha fazla bağlantı açın veya bunun ötesinde iş başlıkları kullanın. Bakızınız Asenkron uygulama (anket yöntemi).

İş zincirleri, birkaç operasyonu uçuşta tutmanın diğer yoludur. ODBC, çok iş parçacıklı işletim sistemlerindeki sürücülerin iş akışı güvenli olmasını gerektirir, böylece bir iş parçası engelleyici ODBC çağrısı yapabilirken, diğer iş parçacıkları çalışmaya devam eder. Bu, asenkron modun ihtiyaç duyduğu anket döngüsünü ve tekrarlanan fonksiyon çağrılarını önler. Her konuya kendi ifade kullanıcı adını verin. Bir sürücünün, aynı tanıtıcıyı aynı anda kullanan iki iş parçacığının yürütülmesini serileştirmesi muhtemeldir; bu nedenle tek bir tanıtıcıyı paylaşmak eşzamanlılığı ortadan kaldırır. Bkz. Çoklu iş parçacığı. Yeni kod için iş parçacıklarını tercih edin ve zaten çalışan asenkron kodu dönüştürmeden önce kendi iş yükünüzü ölçün.

Windows'ta sürücü yöneticisi ayrıca bildirim yöntemini destekliyor ve bu da anket döngüsünü kaldırıyor. Bir Win32 olayını bağlantı veya ifade tanıtıcısıyla ilişkilendirirsiniz. Fonksiyon yine hemen geri döner SQL_STILL_EXECUTING ve sürücü yöneticisi işlem tamamlandığında olayı sinyal eder. Yoklama bu modda devre dışıdır: orijinal işlevin yeniden çağrılması, SQLSTATE SQL_ERROR ile IM017 döndürür. Bunun yerine sonucu almak için SQLCompleteAsync çağrısını yapın. Bunun sürücü yöneticisi ODBC 3.81 ve daha sonraki sürümleri gerektirir ve sürücünün de desteklemesi gerekir. Kontrol etmek için SQL_ASYNC_NOTIFICATION ile SQLGetInfo numarasını arayın. Aldığınız değer, uygulamanızın bildirdiği ODBC sürümüne bağlıdır: SQL Server için Microsoft ODBC Driver 18 kullanıldığında, SQL_ATTR_ODBC_VERSION değerini SQL_ASYNC_NOTIFICATION_CAPABLE olarak ayarlayan bir uygulama SQL_OV_ODBC3_80 alır ve SQL_OV_ODBC3 bildiren bir uygulama ise aynı sürücüden SQL_ASYNC_NOTIFICATION_NOT_CAPABLE alır. Bağlantıyı tahsis etmeden önce beyan SQL_OV_ODBC3_80 edin. Bakız: Asenkron yürütme (bildirim yöntemi) ve bildirim yöntemi örneği.

Bekleyen bir operasyonu iptal et

SQLCancel hala bir statement handle üzerinde çalışan bir işlemi iptal eder. Bunu başka bir iş parçacığından veya yoklama döngüsünden, bekleyen çağrının tanıtıcısını geçirerek çağırın.

Sadece bunun için kullanın SQLCancel . Artık okumak istemediğiniz bir sonuç kümesini bırakmak için bunun yerine SQLCloseCursor ya da SQLMoreResults çağırın.

sqlncli.h'den msodbcsql.h'ye migrate

SQL Server Native Client emekli edildi, bu yüzden onu kullanan uygulamalar Microsoft ODBC Driver for SQL Server'a geçmeli. API aynı ODBC API'sidir, bu yüzden işin çoğu bağlantı dizesi'deki derleme girdilerinin ve sürücü adının yeniden adlandırılmasını içerir.

SQL Server Yerel İstemcisi SQL Server için Microsoft ODBC Sürücüsü 18
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

Başlık msodbcsql.h hâlâ makroların SQLNCLI_* adını tanımlar, yani onları kullanan kaynak kod derlemeye devam eder. Bu tanımlar ile #ifndef __sqlncli_h__korunur, yani aynı çeviri ünitesinde her iki başlığı da dahil edemezsiniz. sqlncli.h include ifadesini kaldırın.

İki şey devam etmiyor:

  • Bağlı sunucuların ve kataloglarının listelerini döndüren dağıtık sorgu meta veri API fonksiyonları, 'de msodbcsql.hbildirilmez. Bunlar SQL Server Native Client için özeldi.
  • Sürüm 18, bağlantıları varsayılan olarak şifreler ve sunucu sertifikasını doğrular. Native Client ise yapmadı. Native Client ile çalışan bir bağlantı dizesi, sertifika güvenini düzeltene veya Encrypt değerini açıkça ayarlayana kadar ilk bağlantı denemesinde başarısız olabilir. Bağlantı şifreleme sorun giderimine bakınız.

Geri kalan 17 ile 18 versiyon değişiklikleri için bkz. Büyük sürüm farklılıkları.

İlgili içerik

  • Last updated on