Fonction SQLGetDiagField
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 des diagnostics sont requis. Doit prendre l'une des valeurs suivantes :
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 de la sensibilisation Connection-Pool dans un pilote ODBC.
Handle
[Entrée] Handle pour la structure de 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 de diagnostic, RecNumber est ignoré. Si ce n’est pas le cas, il doit être supérieur à 0.
DiagIdentifier
[Entrée] Indique le champ du diagnostic dont la valeur doit être retournée. Pour plus d’informations, consultez la section « Argument DiagIdentifier » 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 ou 16 bits inférieurs d’une mémoire tampon et laisser le bit d’ordre supérieur inchangé.
Si DiagInfoPtr a la valeur NULL, StringLengthPtr retourne toujours le nombre total d’octets (à l’exclusion du caractère d’arrêt Null pour les données de caractères) pouvant être retournés dans la mémoire tampon vers laquelle DiagInfoPtr pointe.
BufferLength
[Entrée] Si DiagIdentifier est un diagnostic défini par ODBC et que 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 dans *DiagInfoPtr est une chaîne Unicode (lors de l’appel de 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 au 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(length) 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, selon le cas.
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 d’arrêt null) disponibles à retourner dans *DiagInfoPtr, pour les données de caractères. Si le nombre d’octets disponibles à retourner est supérieur ou égal à BufferLength, le texte de *DiagInfoPtr est tronqué en BufferLength moins la longueur d’un caractère de terminaison Null.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_NO_DATA.
Diagnostics
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 a indiqué 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.
Lors de l’utilisation d’une notification asynchrone, l’opération asynchrone sur le handle n’était pas 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 tout RecNumber positif 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 :
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 ).
Pour déterminer le nombre de lignes dans la source de données qui ont été affectées lorsque des opérations d’insertion, de suppression ou de mise à jour ont été 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).
Pour déterminer quelle fonction a été 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, de sorte qu’une application peut appeler SQLGetDiagField après n’importe quel appel de fonction ODBC. Il n’existe aucune limite au nombre d’enregistrements de diagnostic pouvant ê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 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 pour les champs d’en-tête et d’enregistrement. L’application peut appeler à nouveau SQLGetDiagField ultérieurement 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 entre-temps, 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 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 en cours d’exécution 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
Des informations de diagnostic peuvent être associées à chaque type de handle. 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. Les 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 dans le champ décrivent les informations de diagnostic retournées par une fonction. Si RecNumber a la valeur 0, le champ se trouve dans l’en-tête de la structure de données de diagnostic et contient donc des données relatives à l’appel de fonction qui a retourné les informations de diagnostic, et non 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 | Retours |
|---|---|---|
| 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 bits SQL_CA2_CRC_EXACT et SQL_CA2_CRC_APPROXIMATE). Le contenu de ce champ est défini uniquement pour les handles d’instruction et uniquement après l’appel de SQLExecute, SQLExecDirect ou SQLMoreResults . L’appel de SQLGetDiagField avec un DiagIdentifier de SQL_DIAG_CURSOR_ROW_COUNT autre qu’un handle d’instruction renvoie 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 connaître les valeurs spécifiques.) Le contenu de ce champ est défini uniquement pour les handles d’instruction et uniquement après un appel à SQLExecute, SQLExecDirect ou SQLMoreResults. L’appel de SQLGetDiagField avec un DiagIdentifier de SQL_DIAG_DYNAMIC_FUNCTION autre qu’un handle d’instruction renvoie 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’instruction et uniquement après un appel à SQLExecute, SQLExecDirect ou SQLMoreResults. L’appel de SQLGetDiagField avec un DiagIdentifier de SQL_DIAG_DYNAMIC_FUNCTION_CODE autre qu’un handle d’instruction renvoie 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 | Code de retour 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 le handle, SQL_SUCCESS sont retournées pour SQL_DIAG_RETURNCODE. |
| SQL_DIAG_ROW_COUNT | SQLLEN | Nombre de lignes affectées par une insertion, une suppression ou une mise à jour effectuée par SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos. Elle est définie 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 descripteurs d’instructions. L’appel de SQLGetDiagField avec un DiagIdentifier de SQL_DIAG_ROW_COUNT autre qu’un handle d’instruction renvoie 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 non diagnostique, 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 Record
Les champs d’enregistrement répertoriés dans le tableau suivant peuvent être inclus dans l’argument DiagIdentifier .
| DiagIdentifier | Type de retour | Retours |
|---|---|---|
| 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 de l’appel ISO. Pour les SQLSTATEs spécifiques à ODBC (tous ceux 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 nombres de paramètres 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 descripteurs 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 se rapportent à 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. Le texte du message de diagnostic n’a pas de longueur maximale. |
| SQL_DIAG_NATIVE | SQLINTEGER | Un code d’erreur natif spécifique au pilote/à la 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 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 descripteurs d’instructions. |
| SQL_DIAG_SERVER_NAME | SQLCHAR * | Chaîne qui indique le nom du serveur auquel l’enregistrement de diagnostic est lié. Elle 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 les mêmes 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, 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-statement | « ALTER TABLE » | SQL_DIAG_ALTER_TABLE |
| assertion-definition | « CREATE ASSERTION » | SQL_DIAG_CREATE_ASSERTION |
| character-set-definition | « CRÉER UN JEU DE CARACTÈRES » | SQL_DIAG_CREATE_CHARACTER_SET |
| collation-definition | « CREATE COLLATION » | SQL_DIAG_CREATE_COLLATION |
| domainn-definition | « 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 |
| cursor-specification | « SÉLECTIONNER LE CURSEUR » | SQL_DIAG_SELECT_CURSOR |
| delete-statement-positioned | « DYNAMIC DELETE CURSOR » | 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 |
| ODBC-procedure-extension | « CALL » | appel SQL_DIAG_ |
| revoke-statement | « REVOKE » | SQL_DIAG_REVOKE |
| schema-definition | « CREATE SCHEMA » | SQL_DIAG_CREATE_SCHEMA |
| translation-definition | « CREATE TRANSLATION » | SQL_DIAG_CREATE_TRANSLATION |
| update-statement-positioned | « CURSEUR DE MISE À JOUR DYNAMIQUE » | SQL_DIAG_DYNAMIC_UPDATE_CURSOR |
| update-statement-searched | « METTRE À JOUR OÙ » | SQL_DIAG_UPDATE_WHERE |
| Unknown | chaîne vide | SQL_DIAG_UNKNOWN_STATEMENT |
Séquence d’enregistrements d’état
Les enregistrements d’état sont positionnés dans une séquence basée sur le numéro de ligne et le 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 à la fois par le gestionnaire de pilotes et par le pilote, le gestionnaire de pilotes est chargé de les commander.
S’il existe au moins deux enregistrements d’état, la séquence des enregistrements est déterminée en premier par le 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 comme étant -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 comme étant -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 tous les erreurs et avertissements de la ligne suivante affectée, et ainsi de suite.
Notes
Le Gestionnaire de pilotes ODBC 3*.x* ne commande pas les enregistrements d’état dans la file d’attente de diagnostics 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 pilote ODBC 3*.x* lorsque SQLExtendedFetch est appelé ou SQLSetPos est appelé sur un curseur qui a été positionné avec SQLExtendedFetch.
Dans chaque ligne, ou pour tous les enregistrements qui ne correspondent pas à une ligne ou pour lesquels le numéro de ligne est inconnu, ou pour tous les enregistrements dont le numéro de ligne 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 infructueux à une fonction.
Les règles suivantes sont utilisées pour déterminer le premier enregistrement dans une ligne. L’enregistrement avec le classement le plus élevé est le premier enregistrement. La source d’un enregistrement (Gestionnaire de pilotes, pilote, passerelle, etc.) n’est pas prise en compte lors du classement des enregistrements.
Erreurs Les enregistrements d’état qui décrivent les erreurs ont le classement le plus élevé. Les règles suivantes sont appliquées aux erreurs de tri :
Les enregistrements qui indiquent un échec de transaction ou un échec possible de transaction sont plus que tous les autres enregistrements.
Si deux enregistrements ou plus décrivent la même condition d’erreur, les SQLSTATEs définis par la spécification CLI Open Group (classes 03 à HZ) dépassent ODBC et SQLSTATEs définis par le pilote.
Aucune valeur de données définie par l’implémentation Les enregistrements d’état qui décrivent les valeurs No Data définies par le pilote (classe 02) ont le deuxième rang le plus élevé.
Avertissements Les 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 dépassent les SQLSTATEs définis par ODBC et définis par le pilote.
Fonctions connexes
| Pour obtenir des informations sur | Consultez |
|---|---|
| Obtention de plusieurs champs d’une structure de données de diagnostic | SQLGetDiagRec, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC