Wytyczne dotyczące programowania

pobierz sterownika ODBC

Ten artykuł opisuje kwestie programistyczne dla aplikacji korzystających ze sterownika Microsoft ODBC dla SQL Server w systemie Linux lub macOS. Niektóre linki prowadzą do materiałów SQL Server Native Client. Te strony dostarczają historycznego kontekstu API.

Wybierz wersję sterownika

W przypadku nowych projektów użyj sterownika Microsoft ODBC Driver 18 for SQL Server, aktualnej serii sterowników. Microsoft ODBC Driver 17 dla SQL Server pozostaje wspierany dla aplikacji, które już go wdrażają, zgodnie z opisem cyklu wsparcia. Sterownik ODBC 13, który był dołączony do SQL Server 2017, kwalifikuje się do rozszerzonego wsparcia do 12 października 2027 roku, tylko na podstawie rozszerzonej umowy wsparcia.

Określ nazwę zainstalowanego sterownika, ujętą w nawiasy klamrowe, w swoim parametry połączenia:

Driver={ODBC Driver 18 for SQL Server}

Driver={ODBC Driver 17 for SQL Server}

W nazwie źródła danych (DSN) w odbc.ini, używaj nazwy bez nawiasów klamrowych, na przykład Driver = ODBC Driver 18 for SQL Server. Informacje o składni DSN można znaleźć w Słowa kluczowe w ciągu połączeń oraz nazwy źródeł danych (DSN).

Aby poznać ustawienia połączenia specyficzne dla wersji, zobacz różnice między głównymi wersjami. Aby uzyskać daty wsparcia i kompatybilność systemu operacyjnego, zobacz cykl życia wsparcia oraz wymagania systemowe.

Zbuduj aplikację

Informacje o lokalizacji plików nagłówkowych, kolejności dyrektyw include, poleceniach kompilacji, nazwach bibliotek oraz przykładzie w C++ można znaleźć tutaj: Rozwijanie aplikacji w językach C i C++ przy użyciu sterownika ODBC oraz Nawiązywanie połączenia i wykonywanie zapytań za pomocą C++ i ODBC.

Aplikacja ODBC może korzystać z Multiple Active Result Sets (MARS) oraz innych specyficznych dla SQL Server funkcji, dodając msodbcsql.h po nagłówkach unixODBC (sql.h, sqlext.h, sqltypes.h, i sqlucode.h). Używaj tych samych symbolicznych nazw dla elementów specyficznych dla SQL Server, co w aplikacjach ODBC na Windows.

Znajdź funkcje sterownika

Zacznij od ODBC Programmer's Reference, aby poznać standardowy interfejs programowania aplikacji (API). Następnie skorzystaj z aktualnej dokumentacji sterownika, aby uzyskać informacje o zachowaniu specyficznym dla sterownika.

Przegląd sterownika Microsoft ODBC dla SQL Server zawiera łącze do dokumentacji sterownika. Poniższe artykuły o natywnym kliencie SQL Server dostarczają kontekstu API dla aplikacji korzystających z tego sterownika na Linuksie i macOS:

• Komunikacja z programem SQL Server (ODBC)
• Obsługa limitu czasu połączeń i zapytań
• Cursors
• Ulepszenia daty/godziny (ODBC)
• Wykonywanie zapytań (ODBC)
• Obsługa błędów i wiadomości
• Uwierzytelnianie Kerberos
• Duże typy zdefiniowane przez użytkownika wspólnego środowiska uruchomieniowego (CLR) (ODBC)
• Wykonywanie transakcji (ODBC). Do transakcji rozproszonych na Linuksie i macOS używaj transakcji XA z DTC.
• Wyniki przetwarzania (ODBC)
• Uruchamianie procedur składowanych
• Wsparcie rzadkich kolumn (ODBC)
• Używanie szyfrowania bez walidacji
• Parametry wartości tabeli
• UTF-8 i UTF-16 dla API poleceń i danych
• Korzystanie z funkcji katalogowych

Limitations

Następujące funkcje nie zostały zweryfikowane pod kątem poprawnego działania w sterowniku ODBC na Linuksie i macOS:

• Połączenie klastra przełączania awaryjnego.
• Transparentne ustalanie adresu IP w sieci przed sterownikiem ODBC 17.
• Śledzenie Built-In Diagnostics (BID) dla ODBC Driver w systemach Linux i macOS w wersjach przed ODBC Driver 17.3.

Nieobsługiwane funkcje

Następujące funkcje nie są dostępne w sterowniku ODBC na Linuksie i macOS:

• Rozproszone transakcje za pomocą atrybutu SQL_ATTR_ENLIST_IN_DTC. Sterownik obsługuje transakcje XA za pośrednictwem Microsoft Distributed Transaction Coordinator (DTC). Więcej informacji można znaleźć w artykule Używaj transakcji XA z DTC.

• Dublowanie bazy danych.

• FILESTREAM.

• Profilowanie wydajności sterownika ODBC, omówione w SQLSetConnectAttr, oraz następujące atrybuty połączenia związane z wydajnością:

  • SQL_COPT_SS_PERF_DATA
  • SQL_COPT_SS_PERF_DATA_LOG
  • SQL_COPT_SS_PERF_DATA_LOG_NOW
  • SQL_COPT_SS_PERF_QUERY
  • SQL_COPT_SS_PERF_QUERY_INTERVAL
  • SQL_COPT_SS_PERF_QUERY_LOG

• SQLBrowseConnect przed wersją 17.2.

• Typy przedziałów C, takie jak SQL_C_INTERVAL_YEAR_TO_MONTH, udokumentowano w Data Type Identifiers and Descriptors.

• Wartość SQL_CUR_USE_ODBC atrybutu SQL_ATTR_ODBC_CURSORS elementu SQLSetConnectAttr.

Obsługuj dane znakowe

W systemach Linux i macOS używaj buforów UTF-16 SQLWCHAR z szerokoznakowych interfejsów API ODBC zamiast natywnego typu wchar_t. Interfejs sterownika wykorzystuje jednostki kodu 16-bitowego.

Kodowania znaków

Dla sterowników ODBC 13 i 13.1 musisz użyć UTF-8 dla danych SQLCHAR. Te wersje nie obsługują żadnych innych kodowań.

Począwszy od sterownika ODBC 17, obsługiwane zestawy znaków i kodowania danych SQLCHAR obejmują:

Po połączeniu sterownik wykrywa bieżące ustawienia regionalne procesu, w którym jest ładowany. Jeśli lokalizacja używa jednego z wymienionych kodowań, sterownik używa tego kodowania dla SQLCHAR danych (wąskoznakowych). W przeciwnym razie domyślnie przyjmuje UTF-8. Domyślnie procesy uruchamiają się w ustawieniach regionalnych C, co powoduje, że sterownik domyślnie przyjmuje UTF-8. Jeśli aplikacja potrzebuje jednego z wymienionych kodowań, wywołaj setlocale przed połączeniem. Określ wyraźnie ustawienia regionalne lub użyj pustego ciągu (na przykład setlocale(LC_ALL, "")), aby użyć ustawień regionalnych środowiska.

W typowym środowisku Linux lub macOS, gdzie kodowanie jest UTF-8, użytkownicy sterownika ODBC 17 aktualizujący z wersji 13 lub 13.1 nie zauważą różnic. Aplikacje korzystające z wymienionego kodowania nie-UTF-8 za pośrednictwem setlocale muszą używać tego kodowania do sterownika i ze sterownika zamiast UTF-8.

Musisz używać UTF-16LE (mały endian) dla danych SQLWCHAR.

Gdy przypisujesz parametry wejściowe za pomocą SQLBindParameter, jeśli określisz wąski typ znaku SQL, taki jak SQL_VARCHAR, sterownik konwertuje dostarczone dane z kodowania klienta na kodowanie po stronie serwera dla tego parametru. Kodowanie zależy od reguł sortowania; nie zawsze jest to strona kodowa 1252. W przypadku parametrów wyjściowych sterownik konwertuje kodowanie określone w informacjach sortowania skojarzonych z danymi do kodowania klienta. Znaki w kodowaniu źródłowym, które nie są reprezentowalne w docelowym kodowaniu, przekształcają się w znak zapytania (?).

Aby uniknąć tej utraty danych podczas wiązania parametrów wejściowych, określ typ znakowy SQL Unicode, taki jak SQL_WVARCHAR. Sterownik konwertuje kodowanie klienta na UTF-16, które może reprezentować wszystkie znaki Unicode. Kolumna lub parametr docelowy musi być również typem Unicode (nchar, nvarchar lub ntext) lub typem z ustawieniami sortowania lub kodowaniem, które może reprezentować wszystkie oryginalne dane źródłowe. Dla parametrów wyjściowych należy określić typ Unicode SQL oraz albo typ Unicode C (SQL_C_WCHAR), który powoduje zwracanie danych jako UTF-16, lub wąski typ C z kodowaniem klienta, który może reprezentować dane źródłowe. UTF-8 zawsze może reprezentować te dane.

Więcej informacji o sortowaniu i kodowaniach można znaleźć w artykule Collation and Unicode support.

Istnieją różnice w konwersji między wersjami Windows a Linux lub macOSiconv:

• Dla strony kodowej 1255 bajt 0xCA konwertuje się na punkt kodowy UTF-16 0x05BA w systemie Windows oraz 0x00CA w systemach macOS i Linuksie w wersjach libiconv wcześniejszych niż 1.15.
• Biblioteki Linuksa iconv bez rewizji Big5/CP950 z 2003 roku (BIG5-2003) nie konwertują poprawnie znaków dodanych w tej rewizji.
• Dla strony kodowej 932 (japoński, Shift-JIS) dekodowanie znaków niezdefiniowanych w standardzie kodowania różni się. Na przykład bajt 0x80 konwertuje się na U+0080 w systemie Windows, a w systemach Linux i macOS może stać się U+30FB, w zależności od wersji iconv.

W sterownikach ODBC 13 i 13.1 rozdzielenie znaków wielobajtowych UTF-8 lub surogatów UTF-16 pomiędzy buforami SQLPutData powoduje uszkodzenie danych. Używaj buforów strumieniowych, które nie kończą się na niepełnej sekwencji bajtów w kodowaniu. To ograniczenie zostało usunięte w sterowniku ODBC nr 17.

W zakresie kodowania znaków, konwersji, wiązania parametrów i rozmiarowania bufora zobacz Znane problemy.

OpenSSL

Począwszy od wersji 17.4 sterownika ODBC, sterownik dynamicznie ładuje OpenSSL, co pozwala sterownikowi działać w systemach z wersją 1.0 lub 1.1 bez oddzielnych plików sterownika. Począwszy od wersji 17.9, sterownik obsługuje program OpenSSL 3.0 oprócz poprzednich wersji. Gdy dostępnych jest wiele wersji OpenSSL, sterownik próbuje załadować obsługiwaną wersję ze ścieżek wyszukiwania biblioteki.

OpenSSL 4 nie jest obsługiwany. Na macOS link Homebrew openssl wskazujący na OpenSSL 4 może uniemożliwić sterownikowi ładowanie OpenSSL nawet po zainstalowaniu OpenSSL 3. Sprawdź ścieżkę biblioteki oraz zainstalowane wersje.

Alpine Linux

Domyślny rozmiar stosu dla nowych wątków w musl wynosi 128 KB, chyba że plik wykonywalny wymaga większego domyślnego rozmiaru stosu. Wątek może przekroczyć ten limit, gdy odwołuje się do sterownika. Połącz aplikację ODBC na Alpine Linux z -Wl,-z,stack-size=<size_in_bytes>, aby zażądać większego domyślnego stosu wątku. Aplikacje tworzące wątki o jawnie określonym rozmiarze stosu muszą również wybrać odpowiedni rozmiar dla tych wątków.

Stos głównego wątku i domyślny stos dla nowych wątków to nie to samo ustawienie. W systemach glibc domyślne ustawienie dla nowych wątków zwykle jest zgodne z limitem zasobów stosu procesu, z awaryjnym rozwiązaniem specyficznym dla architektury, gdy ten limit jest nieograniczony. Nie zakładaj domyślnej stałej wartości 2 MB we wszystkich systemach Linux.

Dodatkowe uwagi

Aby utworzyć dedykowane połączenie administratora (DAC) z aplikacji ODBC, ustaw Server=tcp:<server>,<dac_port> w swoim ciągu połączenia. Użyj odkrytego portu DAC, a nie zwykłego portu połączenia instancji. Na przykład, jeśli port DAC to 33000, ustaw Server=tcp:<server>,33000. Fragmenty tych ciągów połączeń określają tylko punkt końcowy, a nie uwierzytelnianie. Konfiguruj uwierzytelnianie i walidację certyfikatu serwera osobno.

Login musi należeć do roli serwera sysadmin. Dostęp zdalny wymaga włączenia opcji zdalnych połączeń administracyjnych serwera. Informacje o wymaganiach dostępu, konfiguracji serwera oraz procedurach administrowania z wiersza poleceń można znaleźć w sekcji Połączenie diagnostyczne dla administratorów baz danych. Informacje o wykrywaniu portów znajdziesz w porcie DAC.

Menedżer sterowników unixODBC obsługuje atrybuty instrukcji przekazywane SQLSetConnectAttr w ten sam sposób co Windows Driver Manager. Opcje instrukcji ODBC 2.x, takie jak SQL_ATTR_QUERY_TIMEOUT i SQL_ATTR_MAX_ROWS, mają zastosowanie do istniejących i nowych instrukcji w połączeniu. Atrybuty tylko dla instrukcji ODBC 3.x, takie jak SQL_ATTR_ROW_ARRAY_SIZE i SQL_ATTR_PARAMSET_SIZE, zwracają SQLSTATE HY092. Atrybuty zdefiniowane zarówno na poziomie połączenia, jak i instrukcji, takie jak SQL_ATTR_METADATA_ID, mogą być ustawiane na jednym z tych poziomów. Ustawianie atrybutów tylko dla instrukcji na poziomie połączenia jest przestarzałe w ODBC 3.x, więc zamiast tego wywołaj SQLSetStmtAttr. Więcej informacji można znaleźć w funkcji SQLSetConnectAttr.

W aplikacjach wysoce wielowątkowych walidacja uchwytów unixODBC może stać się wąskim gardłem wydajności. Kompilacja unixODBC z użyciem --enable-fastvalidate może poprawić wydajność. Jednak ta opcja może spowodować, że aplikacje przekazujące nieprawidłowe uchwyty do interfejsów API ODBC ulegną awarii zamiast zwracać SQL_INVALID_HANDLE.

Kroki instalacji i konfiguracji platformy można znaleźć, zobacz:

• Zainstaluj sterownik ODBC na Linuksie.
• Zainstaluj sterownik ODBC na macOS.
• Zainstaluj menedżera sterowników unixODBC.
• Konfiguruj ciągi połączeń i DSN-y.
• Przejrzyj wymagania systemowe.

Treści powiązane

• Najczęściej zadawane pytania dotyczące ODBC na Linuksie i macOS
• Notatki do wydania sterownika Microsoft ODBC dla SQL Server on Linux i macOS