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 :

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 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).

3. 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 .

Champs Record

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

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.

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.

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

Voir aussi

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