Enregistrements et champs de diagnostic
Les enregistrements de diagnostic sont associés aux handles d'environnement, de connexion, d'instruction ou de descripteur ODBC. Lorsqu'une fonction ODBC déclenche un code de retour autre que SQL_SUCCESS ou SQL_INVALID_HANDLE, le handle appelé par la fonction est associé à des enregistrements de diagnostic qui contiennent des messages informationnels ou d'erreur. Ces enregistrements sont conservés jusqu'à ce qu'une autre fonction soit appelée à l'aide de ce handle, après quoi les enregistrements sont ignorés. Le nombre d'enregistrements de diagnostic pouvant être associés à un handle à un instant donné n'est pas limité.
Les enregistrements de diagnostic sont de deux types : en-tête et état. L'enregistrement d'en-tête est l'enregistrement 0 ; lorsque des enregistrements d'état sont présents, ils prennent les valeurs 1 et supérieures. Les enregistrements de diagnostic contiennent des champs différents pour l'enregistrement d'en-tête et les enregistrements d'état. Des composants ODBC peuvent également définir leurs propres champs d'enregistrement de diagnostic.
Les champs dans l'enregistrement d'en-tête contiennent des informations générales sur l'exécution d'une fonction, y compris le code de retour, le nombre de lignes, le nombre d'enregistrements d'état et le type d'instruction exécutée. L'enregistrement d'en-tête est toujours créé à moins qu'une fonction ODBC ne retourne SQL_INVALID_HANDLE. Pour obtenir la liste complète des champs dans l'enregistrement d'en-tête, consultez SQLGetDiagField.
Les champs dans les enregistrements d'état contiennent des informations sur des erreurs ou des avertissements spécifiques retournés par le gestionnaire de pilotes, le pilote ou la source de données ODBC, y compris la valeur SQLSTATE, le numéro d'erreur native, le message de diagnostic, le numéro de colonne et le numéro de ligne. Les enregistrements d'état sont créés uniquement si la fonction retourne SQL_ERROR, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_NEED_DATA ou SQL_STILL_EXECUTING. Pour obtenir la liste complète des champs dans les enregistrements d'état, consultez SQLGetDiagField.
SQLGetDiagRec récupère un enregistrement de diagnostic unique avec sa valeur SQLSTATE ODBC, son numéro d'erreur native et ses champs de message de diagnostic. Cette fonctionnalité est semblable à celle de la fonction ODBC 2.xSQLError. La fonction de gestion des erreurs la plus simple dans ODBC 3.x consiste à appeler SQLGetDiagRec à plusieurs reprises, en commençant avec la valeur 1 attribuée au paramètre RecNumber et en incrémentant RecNumber d'une unité jusqu'à ce que SQLGetDiagRec retourne SQL_NO_DATA. C'est comme si une application ODBC 2.x appelait SQLError jusqu'à ce qu'elle retourne SQL_NO_DATA_FOUND.
ODBC 3.x prend en charge beaucoup plus d'informations de diagnostic qu'ODBC 2.x. Ces informations sont stockées dans des champs supplémentaires dans les enregistrements de diagnostic récupérés à l'aide de SQLGetDiagField.
Le pilote ODBC SQL Server Native Client comprend des champs de diagnostic spécifiques au pilote qui peuvent être récupérés à l'aide de SQLGetDiagField. Les étiquettes pour ces champs spécifiques au pilote sont définies dans sqlncli.h. Utilisez ces étiquettes pour récupérer l'état SQL Server, le niveau de gravité, le nom du serveur, le nom de la procédure et le numéro de ligne associés à chaque enregistrement de diagnostic. Par ailleurs, sqlncli.h contient des définitions des codes que le pilote utilise pour identifier des instructions Transact-SQL si une application appelle SQLGetDiagField avec DiagIdentifier ayant pour valeur SQL_DIAG_DYNAMIC_FUNCTION_CODE.
SQLGetDiagField est traité par le gestionnaire de pilotes ODBC à l'aide d'informations sur l'erreur qu'il met en cache à partir du pilote sous-jacent. Le gestionnaire de pilotes ODBC ne met pas en cache les champs de diagnostic spécifiques aux pilotes tant qu'une connexion n'a pas été établie avec succès. SQLGetDiagField retourne SQL_ERROR s'il est appelé pour obtenir des champs de diagnostic spécifiques au pilote avant l'établissement d'une connexion. Si une fonction de connexion ODBC retourne SQL_SUCCESS_WITH_INFO, les champs de diagnostic spécifiques au pilote pour la fonction de connexion ne sont pas encore disponibles. Vous pouvez commencer à appeler SQLGetDiagField au sujet des champs de diagnostic spécifiques au pilote uniquement après avoir effectué un autre appel de fonction ODBC après la fonction de connexion.
La plupart des erreurs signalées par le pilote ODBC SQL Server Native Client peuvent être diagnostiquées efficacement à l'aide des informations retournées exclusivement par SQLGetDiagRec. Toutefois, dans certains cas, les informations retournées par les champs de diagnostic spécifiques au pilote sont importantes pour diagnostiquer une erreur. Lors du codage d'un gestionnaire d'erreurs ODBC pour des applications à l'aide du pilote ODBC SQL Server Native Client, il est également conseillé d'utiliser SQLGetDiagField pour récupérer au moins les champs spécifiques au pilote SQL_DIAG_SS_MSGSTATE et SQL_DIAG_SS_SEVERITY. Si une erreur particulière peut être déclenchée à plusieurs endroits dans le code SQL Server, SQL_DIAG_SS_MSGSTATE indique à un ingénieur du support technique Microsoft l'emplacement précis où une erreur a été déclenchée, ce qui peut parfois s'avérer utile pour diagnostiquer un problème.