Instructions de programmation

Télécharger le pilote ODBC

Cet article décrit les considérations de programmation pour les applications qui utilisent le pilote Microsoft ODBC pour SQL Server sur Linux ou macOS. Certains liens font référence à la documentation de SQL Server Native Client. Ces pages fournissent un contexte historique de l’API.

Choisissez une version de pilote

Utilisez le pilote ODBC 18 de Microsoft pour SQL Server, la ligne de pilotes actuelle, pour le nouveau développement. Le pilote Microsoft ODBC 17 pour SQL Server reste pris en charge pour les applications qui le déploient déjà, comme décrit dans le cycle de vie de support. Le pilote ODBC 13, qui a été livré avec SQL Server 2017, est éligible à un support étendu jusqu’au 12 octobre 2027, uniquement dans le cadre d’un accord de support prolongé.

Spécifiez le nom du pilote installé dans votre chaîne de connexion, entre accolades :

Driver={ODBC Driver 18 for SQL Server}

Driver={ODBC Driver 17 for SQL Server}

Dans un nom de source de données (DSN) dans odbc.ini, utilisez le nom sans accolades, par exemple Driver = ODBC Driver 18 for SQL Server. Pour la syntaxe DSN, voir Mots-clés de chaînes de connexion et noms de sources de données (DSN).

Pour les paramètres de connexion spécifiques à chaque version, voir Différences majeures de version. Pour les dates de support et la compatibilité du système d’exploitation, voir le cycle de vie du support et les exigences système.

Créer une application

Pour les emplacements des en-têtes, incluez l’ordre des inclusions, les commandes du compilateur, les noms de bibliothèques et un exemple C++, voir Développer des applications C et C++ avec le pilote ODBC et Se connecter et interroger avec C++ et ODBC.

Une application ODBC peut utiliser des ensembles de résultats actifs multiples (MARS) et d’autres fonctionnalités spécifiques à SQL Server en incluant msodbcsql.h après les en-têtes unixODBC (sql.h, sqlext.h, sqltypes.h, et sqlucode.h). Utilisez les mêmes noms symboliques pour les éléments spécifiques à SQL Server que vous utilisez dans les applications ODBC Windows.

Rechercher les fonctionnalités du pilote

Commencez par le Guide du programmeur ODBC pour l’interface standard de programmation d’applications (API). Ensuite, utilisez la documentation actuelle du pilote pour le comportement spécifique au pilote.

L’aperçu du pilote Microsoft ODBC pour SQL Server renvoie à la documentation du pilote. Les articles suivants sur SQL Server Native Client fournissent un contexte API pour les applications utilisant ce pilote sous Linux et macOS :

Limitations

Les fonctionnalités suivantes n’ont pas été vérifiées pour fonctionner correctement dans le pilote ODBC sur Linux et macOS :

Fonctionnalités non prises en charge

Les fonctionnalités suivantes ne sont pas disponibles dans le pilote ODBC sur Linux et macOS :

  • Transactions distribuées via l’attribut SQL_ATTR_ENLIST_IN_DTC . Le pilote prend en charge les transactions XA via le Microsoft Distributed Transaction Coordinator (DTC). Pour plus d’informations, voir Utiliser les transactions XA avec DTC.

  • Mise en miroir de bases de données.

  • FILESTREAM.

  • Profilage de la performance des pilotes ODBC, comme indiqué dans SQLSetConnectAttr, et ces attributs de connexion liés à la performance :

    • 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 avant la version 17.2.

  • Les types d’intervalles C tels que SQL_C_INTERVAL_YEAR_TO_MONTH, documentés dans Data Type Identifiers and Descriptors.

  • La valeur SQL_CUR_USE_ODBC de l’attribut SQL_ATTR_ODBC_CURSORS de SQLSetConnectAttr.

Traiter les données de caractères

Sous Linux et macOS, utilisez des tampons UTF-16 SQLWCHAR avec des API ODBC à caractères larges au lieu du type natif wchar_t . L’interface du pilote utilise des unités de code 16 bits.

Codages de caractères

Pour les pilotes ODBC 13 et 13.1, vous devez utiliser UTF-8 pour les données SQLCHAR. Ces versions ne prennent en charge aucun autre encodage.

À partir du pilote ODBC 17, les ensembles de caractères et codages pris en charge pour SQLCHAR les données incluent :

Note

En raison des iconv différences entre musl et glibc, beaucoup de ces paramètres régionaux ne sont pas pris en charge sur Alpine Linux. Pour plus d’informations, voir Différences fonctionnelles par rapport à glibc.

Nom Description
UTF-8 Unicode
CP437 MS-DOS ÉTATS-Unis latins
CP850 MS-DOS Latin 1
CP874 Latin/thaï
CP932 Japonais (page de codes Windows 932)
CP936 Chinois simplifié, GBK
CP949 Coréen (page de code Windows 949)
CP950 Chinois traditionnel, Big5
CP1250 Europe centrale
CP1251 Cyrillique
CP1252 Europe occidentale
CP1253 Grec
CP1254 Turc
CP1255 Hébreu
CP1256 Arabe
CP1257 Baltique
CP1258 Vietnamien
ISO-8859-1 Latin-1
ISO-8859-2 Latin-2
ISO-8859-3 Latin-3
ISO-8859-4 Latin-4
ISO-8859-5 Latin/cyrillique
ISO-8859-6 Latin/arabe
ISO-8859-7 Latin/grec
ISO-8859-8 Hébreu
ISO-8859-9 Turc
ISO-8859-13 Latin-7
ISO-8859-15 Latin-9

Lorsque vous établissez la connexion, le pilote détecte le paramètre régional actuel du processus dans lequel il est chargé. Si le paramètre régional utilise l’un des codages listés, le pilote utilise ce codage pour SQLCHAR les données (à caractères étroits). Sinon, il est par défaut UTF-8. Les processus démarrent par défaut dans les C paramètres régionaux, ce qui fait que le pilote passe par défaut à UTF-8. Si une application a besoin de l’un des encodages listés, appelez setlocale avant de vous connecter. Spécifiez explicitement les paramètres régionaux, ou utilisez une chaîne vide (par exemple, setlocale(LC_ALL, "")) pour utiliser les paramètres régionaux de l’environnement.

Dans un environnement Linux ou macOS typique où l’encodage est UTF-8, les utilisateurs du pilote ODBC 17 qui passent de la version 13 ou 13.1 ne constateront pas de différences. Les applications qui utilisent un encodage non UTF-8 listé via setlocale doivent utiliser ce codage pour les données allant et venant du pilote au lieu de l’UTF-8.

Vous devez utiliser UTF-16LE (little endian) pour les données SQLWCHAR.

Lorsque vous liez des paramètres d’entrée en utilisant SQLBindParameter, si vous spécifiez un type SQL à caractères étroits tel que SQL_VARCHAR, le pilote convertit les données fournies de l’encodage client vers l’encodage côté serveur pour ce paramètre. L’encodage dépend de l’ordre de tri ; ce n’est pas toujours la page de codes 1252. Pour les paramètres de sortie, le pilote effectue une conversion depuis l’encodage spécifié dans les informations de classement associées aux données vers l’encodage client. Les caractères de l’encodage source qui ne sont pas représentables dans l’encodage cible se convertissent en point d’interrogation (?).

Pour éviter cette perte de données lors de la liaison de paramètres d’entrée, spécifiez un type de caractère SQL Unicode tel que SQL_WVARCHAR. Le pilote convertit l’encodage client en UTF-16, qui peut représenter tous les caractères Unicode. La colonne ou paramètre cible doit également être un type Unicode (nchar, nvarchar ou ntext) ou un type avec un collation ou un encodage pouvant représenter toutes les données sources originales. Pour les paramètres de sortie, spécifiez un type SQL Unicode et soit un type C Unicode (SQL_C_WCHAR), qui fait renvoyer les données par le pilote sous forme UTF-16, soit un type C étroit avec un encodage client pouvant représenter les données sources. UTF-8 peut toujours représenter ces données.

Pour plus d’informations sur les collations et encodages, voir Collation et prise en charge Unicode.

Il existe des différences de conversion entre Windows et les versions Linux ou macOS iconv :

  • Pour la page de code 1255, l’octet 0xCA se convertit en point de code UTF-16 0x05BA sur Windows et 0x00CA sur macOS et Linux avec des versions de libiconv antérieures à 1.15.
  • Les bibliothèques Linux iconv sans la révision de 2003 de Big5/CP950 (BIG5-2003) ne convertissent pas correctement les caractères ajoutés dans cette révision.
  • Pour la page de code 932 (japonais, Shift-JIS), le décodage des caractères non définis dans la norme d’encodage diffère. Par exemple, byte 0x80 se convertit en U+0080 sous Windows et peut devenir U+30FB sous Linux et macOS, selon la version iconv.

Dans les pilotes ODBC 13 et 13.1, la division des caractères multioctets UTF-8 ou des substituts UTF-16 sur plusieurs tampons SQLPutData entraîne une corruption des données. Utilisez des tampons de streaming qui ne se terminent pas par des encodages partiels de caractères. Cette limitation a été supprimée dans le pilote ODBC 17.

Pour les conseils d’encodage de caractères, de conversion, de liaison de paramètres et de taille de tampon, voir Problèmes connus.

OpenSSL

À partir du pilote ODBC 17.4, le pilote charge OpenSSL dynamiquement, ce qui lui permet de fonctionner sur des systèmes ayant la version 1.0 ou 1.1 sans fichiers de pilotes séparés. À partir de la version 17.9, le pilote prend en charge OpenSSL 3.0 en plus des versions précédentes. Lorsque plusieurs versions d’OpenSSL sont présentes, le pilote tente de charger une version prise en charge depuis ses chemins de recherche de bibliothèque.

Version du pilote Versions OpenSSL prises en charge
17,4 à 17,8 1.0, 1.1
versions 17.x à partir de 17.9, ainsi que toutes les versions du pilote 18 1.0, 1.1, 3.0

OpenSSL 4 n’est pas pris en charge. Sur macOS, un lien Homebrew openssl pointant vers OpenSSL 4 peut empêcher le pilote de charger OpenSSL même lorsque OpenSSL 3 est installé. Vérifiez le chemin de la bibliothèque ainsi que les versions installées.

Note

Un conflit potentiel pourrait survenir si l’application utilisant le pilote, ou l’un de ses composants, établit un lien avec ou charge dynamiquement une version différente d’OpenSSL. Si plusieurs versions d’OpenSSL sont présentes sur le système et que l’application l’utilise, assurez-vous que la version chargée par l’application et le pilote ne sont pas incompatibles. Les erreurs pourraient corrompre la mémoire et ne pas se manifester de manière évidente ou cohérente.

Alpine Linux

La taille de pile par défaut pour les nouveaux threads dans musl est de 128 Ko, sauf si l’exécutable demande une valeur par défaut plus élevée. Un thread peut dépasser cette limite lorsqu’il appelle le pilote. Liez une application ODBC sur Alpine Linux avec -Wl,-z,stack-size=<size_in_bytes> pour demander une pile de threads par défaut plus grande. Les applications qui créent des threads avec une taille de pile explicite doivent également choisir une taille adéquate pour ces threads.

La pile du thread principal et celle par défaut pour les nouveaux threads ne sont pas le même paramètre. Sur les glibc systèmes, la valeur par défaut pour les nouveaux threads suit normalement la limite de ressources de la pile du processus, avec une valeur de repli spécifique à l’architecture lorsque cette limite est illimitée. Ne supposez pas qu'une valeur par défaut fixe de 2 Mo s'applique à tous les systèmes Linux.

Notes supplémentaires

Pour créer une connexion administrateur dédiée (DAC) depuis une application ODBC, définissez Server=tcp:<server>,<dac_port> dans votre chaîne de connexion. Utilisez le port DAC découvert, pas le port de connexion habituel de l’instance. Par exemple, si le port DAC est 33000, réglez Server=tcp:<server>,33000. Ces fragments de chaîne de connexion spécifient uniquement le point de terminaison, pas l’authentification. Configurez séparément l’authentification et la validation du certificat serveur.

L’identifiant de connexion doit être membre du rôle serveur sysadmin. L’accès à distance nécessite d’activer l’option de connexion administrateur distant du serveur. Pour les besoins d’accès, la configuration des serveurs et les procédures d’administration via la ligne de commande, voir Connexion de diagnostic pour les administrateurs de bases de données. Pour la découverte de ports, voir port DAC.

Le gestionnaire de pilotes unixODBC gère les attributs d’instruction transmis SQLSetConnectAttr de la même manière que le gestionnaire de pilotes Windows. Les options d’instruction SQL ODBC 2.x, telles que SQL_ATTR_QUERY_TIMEOUT et SQL_ATTR_MAX_ROWS, s’appliquent aux instructions SQL existantes et nouvelles sur la connexion. Les attributs ODBC 3.x uniquement à l’instruction, tels que SQL_ATTR_ROW_ARRAY_SIZE et SQL_ATTR_PARAMSET_SIZE, retournent SQLSTATE HY092. Les attributs définis à la fois au niveau de connexion et d’instruction, tels que SQL_ATTR_METADATA_ID, peuvent être définis à n’importe quel niveau. Définir uniquement les attributs d’instruction au niveau de la connexion est obsolète dans ODBC 3.x, donc appelez SQLSetStmtAttr à la place. Pour plus d’informations, voir la fonction SQLSetConnectAttr.

Dans les applications très multithreadées, la validation des handles unixODBC peut devenir un goulot d’étranglement en termes de performance. La compilation de unixODBC avec --enable-fastvalidate pourrait améliorer les performances. Cependant, cette option pourrait provoquer le plantage des applications qui passent des handle invalides vers des API ODBC au lieu de renvoyer SQL_INVALID_HANDLE.

Pour les étapes d’installation et de configuration de la plateforme, voir :

Contenu connexe

  • Dernière mise à jour :