Partager via

SQLGetDiagField, fonction

  • Article

conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92

résumé
SQLGetDiagField retourne la valeur actuelle d’un champ d’un enregistrement de la structure de données de diagnostic (associée à un handle spécifié) qui contient des informations d’erreur, d’avertissement et d’état.

Syntaxe


SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);

Arguments

HandleType
[Entrée] Identificateur de type de handle qui décrit le type de handle pour lequel les diagnostics sont requis. Doit être l’un des éléments suivants :

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handle est utilisé uniquement par le Gestionnaire de pilotes et le pilote. Les applications ne doivent pas utiliser ce type de handle. Pour plus d’informations sur SQL_HANDLE_DBC_INFO_TOKEN, consultez Développement Connection-Pool awareness dans unde pilote ODBC.

Handle
[Entrée] Handle pour la structure des données de diagnostic, du type indiqué par HandleType. Si HandleType est SQL_HANDLE_ENV, Handle peut être un handle d’environnement partagé ou non partagé.

RecNumber
[Entrée] Indique l’enregistrement d’état à partir duquel l’application recherche des informations. Les enregistrements d’état sont numérotés à partir de 1. Si l’argument DiagIdentifier indique un champ de l’en-tête diagnostics, RecNumber est ignoré. Si ce n’est pas le cas, il devrait s’agir de plus de 0.

DiagIdentifier
[Entrée] Indique le champ du diagnostic dont la valeur doit être retournée. Pour plus d’informations, consultez la section «DiagIdentifier Argument » dans « Commentaires ».

DiagInfoPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner les informations de diagnostic. Le type de données dépend de la valeur de DiagIdentifier. Si DiagInfoPtr est un type entier, les applications doivent utiliser une mémoire tampon de SQLULEN et initialiser la valeur sur 0 avant d’appeler cette fonction, car certains pilotes peuvent écrire uniquement les 32 bits inférieurs ou 16 bits d’une mémoire tampon et laisser le bit de l’ordre supérieur inchangé.

Si DiagInfoPtr a la valeur NULL, StringLengthPtr retourne toujours le nombre total d’octets (à l’exclusion du caractère de terminaison null pour les données de caractères) disponibles pour retourner dans la mémoire tampon pointée par DiagInfoPtr.

bufferLength
[Entrée] Si DiagIdentifier est un diagnostic défini par ODBC et DiagInfoPtr pointe vers une chaîne de caractères ou une mémoire tampon binaire, cet argument doit être la longueur de *DiagInfoPtr. Si DiagIdentifier est un champ défini par ODBC et * DiagInfoPtr est un entier, bufferLength est ignoré. Si la valeur de *DiagInfoPtr est une chaîne Unicode (lors de l’appel SQLGetDiagFieldW), l’argument bufferLength doit être un nombre pair.

Si DiagIdentifier est un champ défini par le pilote, l’application indique la nature du champ dans le Gestionnaire de pilotes en définissant l’argument BufferLength. BufferLength peut avoir les valeurs suivantes :

  • Si DiagInfoPtr est un pointeur vers une chaîne de caractères, bufferLength est la longueur de la chaîne ou SQL_NTS.

  • Si DiagInfoPtr est un pointeur vers une mémoire tampon binaire, l’application place le résultat de la macro SQL_LEN_BINARY_ATTR() dans BufferLength. Cela place une valeur négative dans BufferLength.

  • Si DiagInfoPtr est un pointeur vers une valeur autre qu’une chaîne de caractères ou une chaîne binaire, BufferLength doit avoir la valeur SQL_IS_POINTER.

  • Si *DiagInfoPtr contient un type de données de longueur fixe, BufferLength est SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_IS_USMALLINT, le cas échéant.

stringLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total d’octets (à l’exclusion du nombre d’octets requis pour le caractère de terminaison null) disponible pour retourner dans *DiagInfoPtr, pour les données de caractères. Si le nombre d’octets disponibles pour retourner est supérieur ou égal à BufferLength, le texte dans *DiagInfoPtr est tronqué à BufferLength moins la longueur d’un caractère de terminaison null.

Retourne

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_NO_DATA.

Diagnostic

SQLGetDiagField ne publie pas d’enregistrements de diagnostic pour lui-même. Il utilise les valeurs de retour suivantes pour signaler le résultat de sa propre exécution :

  • SQL_SUCCESS : la fonction a correctement retourné les informations de diagnostic.

  • SQL_SUCCESS_WITH_INFO : *DiagInfoPtr était trop petit pour contenir le champ de diagnostic demandé. Par conséquent, les données du champ de diagnostic ont été tronquées. Pour déterminer qu’une troncation s’est produite, l’application doit comparer BufferLength au nombre réel d’octets disponibles, qui est écrit dans *StringLengthPtr.

  • SQL_INVALID_HANDLE : le handle indiqué par HandleType et Handle n’était pas un handle valide.

  • SQL_ERROR : l’une des opérations suivantes s’est produite :

    • l’argument DiagIdentifier n’était pas l’une des valeurs valides.

    • l’argument DiagIdentifier était SQL_DIAG_CURSOR_ROW_COUNT, SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE ou SQL_DIAG_ROW_COUNT, mais Handle n’était pas un handle d’instruction. (Le Gestionnaire de pilotes retourne ce diagnostic.)

    • l’argument RecNumber était négatif ou 0 lorsque DiagIdentifier indiquait un champ à partir d’un enregistrement de diagnostic. RecNumber est ignoré pour les champs d’en-tête.

    • La valeur demandée était une chaîne de caractères et BufferLength était inférieure à zéro.

    • Lorsque vous utilisez une notification asynchrone, l’opération asynchrone sur le handle n’a pas été terminée.

  • SQL_NO_DATA : RecNumber était supérieur au nombre d’enregistrements de diagnostic qui existaient pour le handle spécifié dans Handle. La fonction retourne également SQL_NO_DATA pour les de RecNumber positives s’il n’existe aucun enregistrement de diagnostic pour Handle.

Commentaires

Une application appelle généralement SQLGetDiagField pour atteindre l’un des trois objectifs suivants :

  1. Pour obtenir des informations d’erreur ou d’avertissement spécifiques lorsqu’un appel de fonction a retourné SQL_ERROR ou SQL_SUCCESS_WITH_INFO (ou SQL_NEED_DATA pour la fonction SQLBrowseConnect).

  2. Pour déterminer le nombre de lignes dans la source de données affectée lors de l’insertion, de la suppression ou des opérations de mise à jour effectuées avec un appel à SQLExecute, SQLExecDirect, SQLBulkOperations, ou SQLSetPos (à partir du champ d’en-tête SQL_DIAG_ROW_COUNT), ou pour déterminer le nombre de lignes qui existent dans le curseur ouvert actuel, si le pilote peut fournir ces informations (à partir du champ d’en-tête SQL_DIAG_CURSOR_ROW_COUNT).

  3. Pour déterminer la fonction exécutée par un appel à SQLExecDirect ou SQLExecute (à partir des champs d’en-tête SQL_DIAG_DYNAMIC_FUNCTION et SQL_DIAG_DYNAMIC_FUNCTION_CODE).

Toute fonction ODBC peut publier zéro ou plusieurs enregistrements de diagnostic chaque fois qu’elle est appelée, afin qu’une application puisse appeler SQLGetDiagField après tout appel de fonction ODBC. Il n’existe aucune limite au nombre d’enregistrements de diagnostic qui peuvent être stockés à tout moment. SQLGetDiagField récupère uniquement les informations de diagnostic les plus récemment associées à la structure de données de diagnostic spécifiée dans l’argument de Handle. Si l’application appelle une fonction ODBC autre que SQLGetDiagField ou SQLGetDiagRec, toutes les informations de diagnostic d’un appel précédent avec le même handle sont perdues.

Une application peut analyser tous les enregistrements de diagnostic en incrémentant RecNumber, tant que SQLGetDiagField retourne SQL_SUCCESS. Le nombre d’enregistrements d’état est indiqué dans le champ d’en-tête SQL_DIAG_NUMBER. Les appels à SQLGetDiagField ne sont pas destructeurs dans les champs d’en-tête et d’enregistrement. L’application peut appeler SQLGetDiagField plus tard pour récupérer un champ à partir d’un enregistrement, tant qu’une fonction autre que les fonctions de diagnostic n’a pas été appelée dans l’intervalle, ce qui publierait des enregistrements sur le même handle.

Une application peut appeler SQLGetDiagField pour retourner n’importe quel champ de diagnostic à tout moment, à l’exception de SQL_DIAG_CURSOR_ROW_COUNT ou de SQL_DIAG_ROW_COUNT, qui retourne SQL_ERROR si Handle n’est pas un handle d’instruction. Si un autre champ de diagnostic n’est pas défini, l’appel à SQLGetDiagField retourne SQL_SUCCESS (à condition qu’aucun autre diagnostic ne soit rencontré) et qu’une valeur non définie est retournée pour le champ.

Pour plus d’informations, consultez Utilisation de SQLGetDiagRec et SQLGetDiagField et Implémentation de SQLGetDiagRec et SQLGetDiagField.

L’appel d’une API autre que celle exécutée de façon asynchrone génère une « erreur de séquence de fonction » HY010. Toutefois, l’enregistrement d’erreur ne peut pas être récupéré avant la fin de l’opération asynchrone.

HandleType, argument

Chaque type de handle peut avoir des informations de diagnostic associées. L’argument HandleType indique le type de handle de Handle.

Certains champs d’en-tête et d’enregistrement ne peuvent pas être retournés pour les handles d’environnement, de connexion, d’instruction et de descripteur. Ces handles pour lesquels un champ n’est pas applicable sont indiqués dans les sections « Champs d’en-tête » et « Champs d’enregistrement » suivantes.

Si HandleType est SQL_HANDLE_ENV, Handle peut être un handle d’environnement partagé ou non partagé.

Aucun champ de diagnostic d’en-tête spécifique au pilote ne doit être associé à un handle d’environnement.

Les seuls champs d’en-tête de diagnostic définis pour un handle de descripteur sont SQL_DIAG_NUMBER et SQL_DIAG_RETURNCODE.

DiagIdentifier Argument

Cet argument indique l’identificateur du champ requis à partir de la structure des données de diagnostic. Si RecNumber est supérieur ou égal à 1, les données du champ décrivent les informations de diagnostic retournées par une fonction. Si RecNumber est 0, le champ se trouve dans l’en-tête de la structure des données de diagnostic et contient donc des données relatives à l’appel de fonction qui a retourné les informations de diagnostic, et non pas aux informations spécifiques.

Les pilotes peuvent définir des champs d’en-tête et d’enregistrement spécifiques au pilote dans la structure des données de diagnostic.

Une application ODBC 3*.x* fonctionnant avec un pilote ODBC 2*.x* peut appeler SQLGetDiagField uniquement avec un argument DiagIdentifier de SQL_DIAG_CLASS_ORIGIN, SQL_DIAG_CLASS_SUBCLASS_ORIGIN, SQL_DIAG_CONNECTION_NAME, SQL_DIAG_MESSAGE_TEXT, SQL_DIAG_NATIVE, SQL_DIAG_NUMBER, SQL_DIAG_RETURNCODE, SQL_DIAG_SERVER_NAME, ou SQL_DIAG_SQLSTATE. Tous les autres champs de diagnostic retournent SQL_ERROR.

Champs d’en-tête

Les champs d’en-tête répertoriés dans le tableau suivant peuvent être inclus dans l’argument DiagIdentifier.

DiagIdentifier Type de retour Retourne
SQL_DIAG_CURSOR_ROW_COUNT SQLLEN Ce champ contient le nombre de lignes dans le curseur. Sa sémantique dépend des types d’informations SQLGetInfo SQL_DYNAMIC_CURSOR_ATTRIBUTES2, SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES2, SQL_KEYSET_CURSOR_ATTRIBUTES2 et SQL_STATIC_CURSOR_ATTRIBUTES2, qui indiquent le nombre de lignes disponibles pour chaque type de curseur (dans les SQL_CA2_CRC_EXACT et SQL_CA2_CRC_APPROXIMATE bits).

Le contenu de ce champ est défini uniquement pour les handles d’instructions et uniquement après SQLExecute, SQLExecDirectou SQLMoreResults a été appelé. L’appel SQLGetDiagField avec un DiagIdentifier de SQL_DIAG_CURSOR_ROW_COUNT sur un autre handle d’instruction retourne SQL_ERROR.
SQL_DIAG_DYNAMIC_FUNCTION SQLCHAR * Il s’agit d’une chaîne qui décrit l’instruction SQL exécutée par la fonction sous-jacente. (Consultez « Valeurs des champs de fonction dynamique », plus loin dans cette section, pour obtenir des valeurs spécifiques.) Le contenu de ce champ est défini uniquement pour les handles d’instructions et uniquement après un appel à sqlExecute, SQLExecDirectou SQLMoreResults. L’appel SQLGetDiagField avec un DiagIdentifier de SQL_DIAG_DYNAMIC_FUNCTION sur un autre handle d’instruction retourne SQL_ERROR. La valeur de ce champ n’est pas définie avant un appel à SQLExecute ou SQLExecDirect.
SQL_DIAG_DYNAMIC_FUNCTION_CODE SQLINTEGER Il s’agit d’un code numérique qui décrit l’instruction SQL exécutée par la fonction sous-jacente. (Consultez « Valeurs des champs de fonction dynamique », plus loin dans cette section, pour obtenir une valeur spécifique.) Le contenu de ce champ est défini uniquement pour les handles d’instructions et uniquement après un appel à sqlExecute, SQLExecDirectou SQLMoreResults. L’appel SQLGetDiagField avec un DiagIdentifier de SQL_DIAG_DYNAMIC_FUNCTION_CODE autre qu’un handle d’instruction retourne SQL_ERROR. La valeur de ce champ n’est pas définie avant un appel à SQLExecute ou SQLExecDirect.
SQL_DIAG_NUMBER SQLINTEGER Nombre d’enregistrements d’état disponibles pour le handle spécifié.
SQL_DIAG_RETURNCODE SQLRETURN Retourne le code retourné par la fonction. Pour obtenir la liste des codes de retour, consultez Codes de retour. Le pilote n’a pas besoin d’implémenter SQL_DIAG_RETURNCODE ; il est toujours implémenté par le Gestionnaire de pilotes. Si aucune fonction n’a encore été appelée sur lehandle de , SQL_SUCCESS est retournée pour SQL_DIAG_RETURNCODE.
SQL_DIAG_ROW_COUNT SQLLEN Nombre de lignes affectées par une insertion, une suppression ou une mise à jour effectuées par sqlExecute, SQLExecDirect, SQLBulkOperationsou SQLSetPos. Il est défini par le pilote après l’exécution d’une spécification de curseur . Le contenu de ce champ est défini uniquement pour les handles d’instructions. L’appel SQLGetDiagField avec un DiagIdentifier de SQL_DIAG_ROW_COUNT autres qu’un handle d’instruction retourne SQL_ERROR. Les données de ce champ sont également retournées dans l’argument RowCountPtr de SQLRowCount. Les données de ce champ sont réinitialisées après chaque appel de fonction nondiagnostique, tandis que le nombre de lignes retourné par SQLRowCount reste le même jusqu’à ce que l’instruction soit rétablie à l’état préparé ou alloué.

Champs d’enregistrement

Les champs d’enregistrement répertoriés dans le tableau suivant peuvent être inclus dans l’argument DiagIdentifier.

DiagIdentifier Type de retour Retourne
SQL_DIAG_CLASS_ORIGIN SQLCHAR * Chaîne qui indique le document qui définit la partie classe de la valeur SQLSTATE dans cet enregistrement. Sa valeur est « ISO 9075 » pour tous les SQLSTATEs définis par Open Group et l’interface au niveau des appels ISO. Pour les SQLSTATEs spécifiques à ODBC (toutes celles dont la classe SQLSTATE est « IM »), sa valeur est « ODBC 3.0 ».
SQL_DIAG_COLUMN_NUMBER SQLINTEGER Si le champ SQL_DIAG_ROW_NUMBER est un numéro de ligne valide dans un ensemble de lignes ou un ensemble de paramètres, ce champ contient la valeur qui représente le numéro de colonne dans le jeu de résultats ou le numéro de paramètre dans l’ensemble de paramètres. Les numéros de colonne du jeu de résultats commencent toujours à 1 ; si cet enregistrement d’état se rapporte à une colonne de signet, le champ peut être égal à zéro. Les numéros de paramètre commencent à 1. Elle a la valeur SQL_NO_COLUMN_NUMBER si l’enregistrement d’état n’est pas associé à un numéro de colonne ou un numéro de paramètre. Si le pilote ne peut pas déterminer le numéro de colonne ou le numéro de paramètre auquel cet enregistrement est associé, ce champ a la valeur SQL_COLUMN_NUMBER_UNKNOWN.

Le contenu de ce champ est défini uniquement pour les handles d’instructions.
SQL_DIAG_CONNECTION_NAME SQLCHAR * Chaîne qui indique le nom de la connexion à laquelle l’enregistrement de diagnostic est lié. Ce champ est défini par le pilote. Pour les structures de données de diagnostic associées au handle d’environnement et pour les diagnostics qui ne sont liés à aucune connexion, ce champ est une chaîne de longueur nulle.
SQL_DIAG_MESSAGE_TEXT SQLCHAR * Message d’information sur l’erreur ou l’avertissement. Ce champ est mis en forme comme décrit dans messages de diagnostic. Il n’y a pas de longueur maximale au texte du message de diagnostic.
SQL_DIAG_NATIVE SQLINTEGER Code d’erreur natif spécifique à un pilote/source de données. S’il n’existe aucun code d’erreur natif, le pilote retourne 0.
SQL_DIAG_ROW_NUMBER SQLLEN Ce champ contient le numéro de ligne dans l’ensemble de lignes, ou le numéro de paramètre dans l’ensemble de paramètres, auquel l’enregistrement d’état est associé. Les numéros de ligne et les numéros de paramètre commencent par 1. Ce champ a la valeur SQL_NO_ROW_NUMBER si cet enregistrement d’état n’est pas associé à un numéro de ligne ou un numéro de paramètre. Si le pilote ne peut pas déterminer le numéro de ligne ou le numéro de paramètre auquel cet enregistrement est associé, ce champ a la valeur SQL_ROW_NUMBER_UNKNOWN.

Le contenu de ce champ est défini uniquement pour les handles d’instructions.
SQL_DIAG_SERVER_NAME SQLCHAR * Chaîne qui indique le nom du serveur auquel l’enregistrement de diagnostic est lié. Il est identique à la valeur retournée pour un appel à SQLGetInfo avec l’option SQL_DATA_SOURCE_NAME. Pour les structures de données de diagnostic associées au handle d’environnement et pour les diagnostics qui ne sont liés à aucun serveur, ce champ est une chaîne de longueur nulle.
SQL_DIAG_SQLSTATE SQLCHAR * Code de diagnostic SQLSTATE à cinq caractères. Pour plus d’informations, consultez SQLSTATEs .
SQL_DIAG_SUBCLASS_ORIGIN SQLCHAR * Chaîne avec le même format et valeurs valides que SQL_DIAG_CLASS_ORIGIN, qui identifie la partie définissante de la partie sous-classe du code SQLSTATE. Les SQLSTATES spécifiques à ODBC pour lesquels « ODBC 3.0 » est retourné sont les suivants :

01S00, 01S01, 01S02, 01S06, 01S07, 07S01, 08S01, 21S01, 21S02, 25S01, 25S02, 25S03, 42S01, 42S02, 42S11, 42S12, 42S21, 42S22, HY095, HY097, HY098, HY0999, HY0999, HY100, HY101, HY105, HY107, HY109, HY110, HY111, HYT00, HYT01, IM001, IM002, IM003, IM004, IM005, IM006, IM007, IM008, IM010, IM011, IM012.

Valeurs des champs de fonction dynamique

Le tableau suivant décrit les valeurs de SQL_DIAG_DYNAMIC_FUNCTION et de SQL_DIAG_DYNAMIC_FUNCTION_CODE qui s’appliquent à chaque type d’instruction SQL exécutée par un appel à SQLExecute ou SQLExecDirect. Le pilote peut ajouter des valeurs définies par le pilote à celles répertoriées.

Instruction SQL

exécuté		 Valeur de

SQL_DIAG_DYNAMIC_FUNCTION		 Valeur de

SQL_DIAG_DYNAMIC_FUNCTION_CODE
alter-domain-statement « ALTER DOMAIN » SQL_DIAG_ALTER_DOMAIN
alter-table « ALTER TABLE » SQL_DIAG_ALTER_TABLE
de définition d’assertion « CREATE ASSERTION » SQL_DIAG_CREATE_ASSERTION
définition de jeu de caractères « CREATE CHARACTER SET » SQL_DIAG_CREATE_CHARACTER_SET
définition de classement « CREATE COLLATION » SQL_DIAG_CREATE_COLLATION
de définition de domaine « CREATE DOMAIN » SQL_DIAG_CREATE_DOMAIN
create-index-statement « CREATE INDEX » SQL_DIAG_CREATE_INDEX
create-table-statement « CREATE TABLE » SQL_DIAG_CREATE_TABLE
create-view-statement « CREATE VIEW » SQL_DIAG_CREATE_VIEW
de spécification de curseur « SÉLECTIONNER LE CURSEUR » SQL_DIAG_SELECT_CURSOR
delete-statement-position « CURSEUR DE SUPPRESSION DYNAMIQUE » SQL_DIAG_DYNAMIC_DELETE_CURSOR
delete-statement-searched « DELETE WHERE » SQL_DIAG_DELETE_WHERE
drop-assertion-statement « DROP ASSERTION » SQL_DIAG_DROP_ASSERTION
drop-character-set-stmt « DROP CHARACTER SET » SQL_DIAG_DROP_CHARACTER_SET
drop-collation-statement « DROP COLLATION » SQL_DIAG_DROP_COLLATION
drop-domain-statement « DROP DOMAIN » SQL_DIAG_DROP_DOMAIN
drop-index-statement « DROP INDEX » SQL_DIAG_DROP_INDEX
drop-schema-statement « DROP SCHEMA » SQL_DIAG_DROP_SCHEMA
drop-table-statement « DROP TABLE » SQL_DIAG_DROP_TABLE
drop-translation-statement « DROP TRANSLATION » SQL_DIAG_DROP_TRANSLATION
drop-view-statement « DROP VIEW » SQL_DIAG_DROP_VIEW
grantstatement « GRANT » SQL_DIAG_GRANT
insert-statement « INSERT » SQL_DIAG_INSERT
d’extension de procédure ODBC « APPELER » appel de SQL_DIAG_
revoke-statement « REVOKE » SQL_DIAG_REVOKE
de définition de schéma « CREATE SCHEMA » SQL_DIAG_CREATE_SCHEMA
définition de traduction « CREATE TRANSLATION » SQL_DIAG_CREATE_TRANSLATION
positionnée sur l’instruction update « CURSEUR DE MISE À JOUR DYNAMIQUE » SQL_DIAG_DYNAMIC_UPDATE_CURSOR
de mise à jour de l’instruction « UPDATE WHERE » SQL_DIAG_UPDATE_WHERE
Inconnu chaîne vide SQL_DIAG_UNKNOWN_STATEMENT

Séquence d’enregistrements d’état

Les enregistrements d’état sont positionnés dans une séquence en fonction du numéro de ligne et du type du diagnostic. Le Gestionnaire de pilotes détermine l’ordre final dans lequel retourner les enregistrements d’état qu’il génère. Le pilote détermine l’ordre final dans lequel retourner les enregistrements d’état qu’il génère.

Si les enregistrements de diagnostic sont publiés par le Gestionnaire de pilotes et le pilote, le Gestionnaire de pilotes est chargé de les commander.

S’il existe deux enregistrements d’état ou plus, la séquence des enregistrements est déterminée en premier par numéro de ligne. Les règles suivantes s’appliquent à la détermination de la séquence d’enregistrements de diagnostic par ligne :

  • Les enregistrements qui ne correspondent à aucune ligne apparaissent devant les enregistrements correspondant à une ligne particulière, car SQL_NO_ROW_NUMBER est défini sur -1.

  • Les enregistrements pour lesquels le numéro de ligne est inconnu apparaissent devant tous les autres enregistrements, car SQL_ROW_NUMBER_UNKNOWN est défini sur -2.

  • Pour tous les enregistrements relatifs à des lignes spécifiques, les enregistrements sont triés par la valeur dans le champ SQL_DIAG_ROW_NUMBER. Toutes les erreurs et avertissements de la première ligne affectée sont répertoriés, puis toutes les erreurs et avertissements de la ligne suivante affectée, et ainsi de suite.

Note

Le Gestionnaire de pilotes ODBC 3*.x* ne trie pas les enregistrements d’état dans la file d’attente de diagnostic si SQLSTATE 01S01 (Erreur dans la ligne) est retourné par un pilote ODBC 2*.x* ou si SQLSTATE 01S01 (Erreur dans la ligne) est retourné par un ODBC Pilote 3*.x* quand SQLExtendedFetch est appelé ou SQLSetPos est appelé sur un curseur positionné avec SQLExtendedFetch.

Dans chaque ligne, ou pour tous les enregistrements qui ne correspondent pas à une ligne ou dont le numéro de ligne est inconnu, ou pour tous ces enregistrements dont le nombre de lignes est égal à SQL_NO_ROW_NUMBER, le premier enregistrement répertorié est déterminé à l’aide d’un ensemble de règles de tri. Après le premier enregistrement, l’ordre des autres enregistrements affectant une ligne n’est pas défini. Une application ne peut pas supposer que les erreurs précèdent les avertissements après le premier enregistrement. Les applications doivent analyser la structure complète des données de diagnostic pour obtenir des informations complètes sur un appel infructueuse à une fonction.

Les règles suivantes sont utilisées pour déterminer le premier enregistrement dans une ligne. L’enregistrement avec le rang le plus élevé est le premier enregistrement. La source d’un enregistrement (Gestionnaire de pilotes, pilote, passerelle, et ainsi de suite) n’est pas prise en compte lors du classement des enregistrements.

  • Erreurs Enregistrements d’état qui décrivent les erreurs ont le rang le plus élevé. Les règles suivantes sont appliquées aux erreurs de tri :

    • Enregistrements qui indiquent un échec de transaction ou un échec de transaction possible ont dépassé tous les autres enregistrements.

    • Si deux enregistrements ou plus décrivent la même condition d’erreur, les SQLSTATEs définies par la spécification CLI Open Group (classes 03 à HZ) outrank ODBC et SQLSTATEs définis par le pilote.

  • Valeurs de données non définies par l’implémentation enregistrements Status qui décrivent les valeurs No Data définies par le pilote (classe 02) ont le deuxième rang le plus élevé.

  • Avertissements Enregistrements d’état qui décrivent les avertissements (classe 01) ont le rang le plus bas. Si deux enregistrements ou plus décrivent la même condition d’avertissement, les SQLSTATEs d’avertissement définis par la spécification CLI Open Group outrank ODBC définis et SQLSTATEs définis par le pilote.

Pour plus d’informations sur Voir
Obtention de plusieurs champs d’une structure de données de diagnostic fonction SQLGetDiagRec

Voir aussi

informations de référence sur l’API ODBC
fichiers d’en-tête ODBC