Diagnostics ODBC

Utilisez ces conseils avec le pilote ODBC 17 ou 18 de Microsoft. Il décrit le contrat de diagnostic ODBC ; il ne définit pas de correspondances d’erreurs natives spécifiques à chaque version.

Une fonction ODBC renvoie un code qui décrit le résultat de cet appel. Les dossiers diagnostiques fournissent plus de détails. L’interface de programmation d’applications (API) peut renvoyer des enregistrements provenant du gestionnaire de pilotes, du pilote, de la source de données ou de plusieurs composants. Ne traitez pas le code de retour, SQLSTATE, le code d’erreur natif et le message comme interchangeables.

Interpréter le code de retour

Vérifiez le code de retour avant de traiter la sortie ou de décider s’il faut réessayer. Pour SQL_ERROR et SQL_SUCCESS_WITH_INFO, récupérez les diagnostics à partir du handle utilisé par la fonction. D’autres codes de retour peuvent également avoir des enregistrements de diagnostic lorsque le contrat de fonction le permet.

Code de retour Signification et réponse
SQL_SUCCESS La fonction a été exécutée correctement. Vérifiez le contrat de sortie de la fonction.
SQL_SUCCESS_WITH_INFO La fonction s’est terminée avec des informations d’avertissement. Récupérez chaque enregistrement de diagnostic et vérifiez si la sortie est complète, convertie ou tronquée.
SQL_ERROR La fonction a échoué. Récupérez chaque enregistrement de diagnostic avant d’appeler une autre fonction sur le même handle.
SQL_INVALID_HANDLE La fonction détectait un handle nul ou un handle du mauvais type. ODBC ne fournit pas d’enregistrements de diagnostic pour ce code de retour. Vérifiez la référence de fonction pour des exigences supplémentaires relatives aux handles.
SQL_NO_DATA Aucune autre donnée n’est disponible pour l’opération. Vérifiez la référence de la fonction, car la signification et les enregistrements d’état dépendent de la fonction.

Pour plus d’informations sur le contrat complet de code de retour, voir les codes de retour ODBC.

Récupérez chaque enregistrement de diagnostic

Appelez SQLGetDiagRec pour des enregistrements d’état en commençant par l’enregistrement numéro 1. Continuer jusqu’à ce que la fonction retourne SQL_NO_DATA, ou lire le nombre d’enregistrements depuis l’enregistrement d’en-tête 0 en appelant SQLGetDiagField avec SQL_DIAG_NUMBER. SQLGetDiagRec renvoie SQLSTATE, le code d’erreur natif et le texte du message d’un enregistrement. Utilisez SQLGetDiagField lorsque vous avez besoin d’autres champs d’en-tête ou d’enregistrement.

Ne t’arrête pas après le premier enregistrement. Un composant ODBC peut ajouter un enregistrement d’état contenant des informations sur sa propre couche tout en préservant les diagnostics d’un autre composant. L’ordre et le contenu des enregistrements peuvent aider à identifier l’origine d’une erreur.

Récupérez les dossiers rapidement. Un appel ODBC ultérieur utilisant le même handle remplace sa zone de diagnostic, sauf pour les appels vers SQLGetDiagRec, SQLGetDiagField, et la fonction héritée SQLError . Utilisez SQLGetDiagRec et SQLGetDiagField dans le nouveau code.

SQLGetDiagRec peut renvoyer SQL_SUCCESS_WITH_INFO lorsque son tampon de messages est trop petit. L’enregistrement a été renvoyé, mais le texte du message a été tronqué. Vérifiez la longueur du texte rapportée et récupérez le message avec un tampon plus grand si vous avez besoin du texte complet. Ne confondez pas ce code retour de SQLGetDiagRec avec le code retour de la fonction ODBC originale.

Pour plus d’informations sur la récupération diagnostique, voir Enregistrements de diagnostic, Utilisation de SQLGetDiagRec et SQLGetDiagField, ainsi que les références SQLGetDiagRec et SQLGetDiagField .

Collecte des enregistrements de diagnostic en C++

Utilisez cet assistant C++11 avec un handle ODBC existant. Il appelle SQLGetDiagRecW pour collecter SQLSTATE, le code d’erreur natif et le texte des messages Unicode en mémoire sans enregistrer les messages.

#ifdef _WIN32
#include <windows.h>
#endif
#include <sql.h>
#include <sqlext.h>
#include <algorithm>
#include <limits>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>

struct DiagnosticRecord {
    std::string sqlstate;
    SQLINTEGER native_error;
    std::vector<SQLWCHAR> message;
    bool message_truncated;
};

std::vector<DiagnosticRecord> ReadDiagnostics(SQLSMALLINT type, SQLHANDLE handle) {
    const SQLSMALLINT limit = (std::numeric_limits<SQLSMALLINT>::max)();
    std::vector<DiagnosticRecord> records;
    for (SQLINTEGER number = 1; ; ++number) {
        if (number > limit) {
            throw std::runtime_error("Diagnostic record number exceeds SQLSMALLINT.");
        }
        SQLWCHAR state[6] = {};
        SQLINTEGER native = 0;
        std::vector<SQLWCHAR> message(256);
        auto read = [&]() {
            return SQLGetDiagRecW(type, handle, static_cast<SQLSMALLINT>(number),
                state, &native, message.data(),
                static_cast<SQLSMALLINT>(message.size()), nullptr);
        };

        SQLRETURN result = read();
        if (result == SQL_NO_DATA) {
            return records;
        }
        if (result == SQL_SUCCESS_WITH_INFO) {
            message.resize(limit);
            result = read(); // Retrieve the same record, not the next one.
        }
        if (result != SQL_SUCCESS && result != SQL_SUCCESS_WITH_INFO) {
            throw std::runtime_error("SQLGetDiagRecW couldn't retrieve a diagnostic record.");
        }
        message.erase(std::find(message.begin(), message.end(), SQLWCHAR{0}), message.end());
        records.push_back({
            std::string(state, state + 5),
            native,
            std::move(message),
            result == SQL_SUCCESS_WITH_INFO
        });
    }
}

L’utilitaire réessaie un message tronqué avec la plus grande longueur de tampon positive que SQLGetDiagRecW accepte. Si le message ne tient toujours pas, il conserve le texte disponible et définit message_truncated. Elle continue vers l’enregistrement suivant au lieu de traiter cette troncature comme la fin de la liste de diagnostic. Une exception est levée si la récupération échoue ou si le numéro d’enregistrement dépasse la plage SQLSMALLINT de l’API.

Chaque message contient SQLWCHAR unités de code sans terminateur nul. Ne les réinterprétez pas comme wchar_t, car les types peuvent avoir des largeurs différentes. Convertissez-les en encodage de texte de votre application lorsque vous devez traiter ou afficher le message.

Appelez la fonction d’aide immédiatement après l’opération qui renvoie une erreur ou un avertissement. Ce fragment suppose que statement est un handle d’instruction préparée valide et que l’exécution asynchrone est désactivée :

#include <iostream>

SQLRETURN ExecuteWithDiagnostics(SQLHSTMT statement) {
    SQLRETURN result = SQLExecute(statement);
    if (result == SQL_ERROR || result == SQL_SUCCESS_WITH_INFO) {
        const auto records = ReadDiagnostics(SQL_HANDLE_STMT, statement);
        for (const auto& record : records) {
            std::cerr << "SQLExecute: SQLSTATE=" << record.sqlstate
                      << " native_error=" << record.native_error
                      << " message_truncated=" << record.message_truncated << '\n';
        }
    } else if (result == SQL_INVALID_HANDLE) {
        throw std::runtime_error("SQLExecute returned SQL_INVALID_HANDLE.");
    }
    return result;
}

L’encapsuleur conserve le code de retour original, y compris SQL_SUCCESS_WITH_INFO. Appliquez le même schéma aux autres appels ODBC, en utilisant le type de handle et le handle associés à cette opération. Gérer d’autres codes de retour selon le contrat de cette fonction.

La sortie omet délibérément record.message. Si vous avez besoin de texte de message dans un fichier journal, caviardez-le selon la politique de données de votre application avant de l’écrire. L’assistant ne nettoie pas les messages conservés dans la mémoire.

Lisez les champs de diagnostic

Les champs répondent à différentes questions :

Champ Ce qu’il vous dit
SQLSTATE Un code de cinq caractères qui identifie une condition diagnostique standardisée. Sa classe est composée des deux premiers caractères.
Code d’erreur natif Une valeur spécifique à la source de données ou au composant ODBC. Ce n'est pas un numéro d'erreur universel, et vous ne devriez pas supposer qu'il s'agit d'un numéro d'erreur de SQL Server.
Texte du message Une explication compréhensible par un humain. Lisez-le avec le SQLSTATE et le code d’erreur natif ; ne l’analysez pas comme un contrat stable lisible par machine.

Le gestionnaire de pilotes, le pilote et la source de données peuvent chacun générer des diagnostics. Un composant qui ajoute un enregistrement ne doit pas remplacer ou masquer une erreur ou un avertissement d’un autre composant. Un code d’erreur natif peut être indisponible ou n’avoir aucun sens utile pour un diagnostic généré par un composant. Pour plus d’informations sur les règles de gestion des diagnostics, voir Règles de gestion des diagnostics. Pour plus d’informations sur les classes et valeurs SQLSTATE, voir SQLSTATES.

Utilisez les journaux avec le code de retour de la fonction et l’opération. Par exemple, SQL_SUCCESS_WITH_INFO signifie que la fonction est terminée, mais cela ne garantit pas que chaque valeur de sortie soit complète. Un avertissement de troncature vous oblige à vérifier la longueur retournée et à décider si vous récupérez les données restantes. Pour plus d’informations, voir Longueur des données, longueur du tampon et troncature.

Rassembler des preuves en toute sécurité

Pour un cas de support, enregistrez le nom de la fonction, le type de handle, le code de retour et chaque enregistrement de diagnostic. Incluez les versions du pilote et du gestionnaire de pilotes, le système d’exploitation, l’architecture et le type de source de données. Supprimez les identifiants, les jetons d’accès, les secrets de la chaîne de connexion, le texte de requête, les valeurs des paramètres et les données personnelles ou réglementées avant d’enregistrer ou de partager les résultats. Les messages de diagnostic et les journaux de trace peuvent contenir des données d’application.

Limitez le traçage au scénario de reproduction le plus court dont vous avez besoin. Stockez les journaux dans un répertoire accessible uniquement au compte exécutant l’application, et utilisez un chemin de journal explicite au lieu d’un chemin par défaut partagé ou temporaire. Arrêtez de tracer quand la reproduction se termine, puis retirez le fichier de trace quand vous n’en aurez plus besoin.

Choisissez le calque de traçage

Le diagnostic et le traçage des applications répondent à différentes questions :

Couche Ce qu’il capture Utilisez-le pour
Diagnostic d'application Codes de retour et enregistrements de diagnostic provenant d’appels ODBC individuels Identifiez la fonction qui a échoué ou renvoyé un avertissement, et préserver tous ses champs de diagnostic.
Trace du Gestionnaire de pilotes ODBC Appels API ODBC entre l’application, le gestionnaire de pilotes et le pilote Voyez quels appels l’application a faits et quels codes de retour sont revenus. Les arguments de trace peuvent révéler des valeurs sensibles.
Trace spécifique aux pilotes Événements internes du pilote, lorsque le pilote documente un contrôle supporté Enquêtez sur le comportement du pilote qu’une trace API ne peut pas montrer. Ne partez pas du principe qu’une trace Driver Manager active cette fonctionnalité.

Sous Windows, le gestionnaire de pilotes ODBC supporte le traçage via l’onglet Traçage dans ODBC Data Source Administrator et les attributs SQL_ATTR_TRACE et SQL_ATTR_TRACEFILE. Le traçage est par défaut par utilisateur. Le traçage à l’échelle de la machine nécessite des autorisations d’administrateur local et peut capturer les appels d’applications fonctionnant sous d’autres identités locales. Privilégiez le traçage par utilisateur, et arrêtez-le dès que la reproduction du problème se termine. Pour plus d’informations, voir Paramètres des options de traçage, Activation du traçage et SQLSetConnectAttr.

Sous Linux et macOS, voir Trace d’accès aux données avec le pilote ODBC sur Linux et macOS pour la configuration du gestionnaire de pilotes unixODBC.

Les directives de programmation Linux et macOS existantes conservent une déclaration historique selon laquelle le traçage des diagnostics intégrés (BID) n’a pas été vérifié avant le pilote ODBC 17.3. Cette note ne décrit pas un contrôle de traçage propre au pilote actuel. La procédure unixODBC capture les appels API du gestionnaire de pilotes, et non les événements BID.