SQLGetDiagRec, fonction

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

Résumé
SQLGetDiagRec retourne les valeurs actuelles de plusieurs champs d’un enregistrement de diagnostic qui contient des informations d’erreur, d’avertissement et d’état. Contrairement à SQLGetDiagField, qui retourne un champ de diagnostic par appel, SQLGetDiagRec retourne plusieurs champs couramment utilisés d’un enregistrement de diagnostic, y compris LE SQLSTATE, le code d’erreur natif et le texte du message de diagnostic.

Syntaxe

  
SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);  

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.

SQLState
[Sortie] Pointeur vers une mémoire tampon dans laquelle renvoyer un code SQLSTATE de cinq caractères (et la fin null) pour l’enregistrement de diagnostic RecNumber. Les deux premiers caractères indiquent la classe ; les trois suivants indiquent la sous-classe. Ces informations sont contenues dans le champ de diagnostic SQL_DIAG_SQLSTATE. Pour plus d’informations, consultez SQLSTATEs.

NativeErrorPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le code d’erreur natif, spécifique à la source de données. Ces informations sont contenues dans le champ de diagnostic SQL_DIAG_NATIVE.

MessageText
[Sortie] Pointeur vers une mémoire tampon dans laquelle renvoyer la chaîne de texte du message de diagnostic. Ces informations sont contenues dans le champ de diagnostic SQL_DIAG_MESSAGE_TEXT. Pour connaître le format de la chaîne, consultez Messages de diagnostic.

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

BufferLength
[Entrée] Longueur de la mémoire tampon *MessageText en caractères. Il n’existe aucune longueur maximale du texte du message de diagnostic.

TextLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total de caractères (à l’exclusion du nombre de caractères requis pour le caractère de terminaison null) disponibles pour retourner dans *MessageText. Si le nombre de caractères disponibles à retourner est supérieur à BufferLength, le texte du message de diagnostic dans *MessageText est tronqué en BufferLength moins la longueur d’un caractère de terminaison null.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.

Diagnostics

SQLGetDiagRec 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 : la mémoire tampon *MessageText était trop petite pour contenir le message de diagnostic demandé. Aucun enregistrement de diagnostic n’a été généré. 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 *TextLengthPtr.

• 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 :

  • RecNumber était négatif ou 0.

  • BufferLength était inférieur à zéro.

  • Lors de l’utilisation de la 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 SQLGetDiagRec lorsqu’un appel précédent à une fonction ODBC a retourné SQL_ERROR ou SQL_SUCCESS_WITH_INFO. Toutefois, étant donné qu’une fonction ODBC peut publier zéro ou plusieurs enregistrements de diagnostic chaque fois qu’elle est appelée, une application peut appeler SQLGetDiagRec après n’importe quel appel de fonction ODBC. Une application peut appeler SQLGetDiagRec plusieurs fois pour retourner tout ou partie des enregistrements dans la structure des données de diagnostic. ODBC n’impose aucune limite au nombre d’enregistrements de diagnostic pouvant être stockés à tout moment.

SQLGetDiagRec ne peut pas être utilisé pour retourner des champs à partir de l’en-tête de la structure de données de diagnostic. ( L’argument RecNumber doit être supérieur à 0.) L’application doit appeler SQLGetDiagField à cet effet.

SQLGetDiagRec récupère uniquement les informations de diagnostic les plus récentes associées au handle spécifié dans l’argument Handle . Si l’application appelle une autre fonction ODBC, à l’exception de SQLGetDiagRec, SQLGetDiagField ou SQLError, toutes les informations de diagnostic des appels précédents sur le même handle sont perdues.

Une application peut analyser tous les enregistrements de diagnostic en boucle, en incrémentant RecNumber, tant que SQLGetDiagRec retourne SQL_SUCCESS. Les appels à SQLGetDiagRec ne sont pas destructeurs pour les champs d’en-tête et d’enregistrement. L’application peut appeler à nouveau SQLGetDiagRec ultérieurement pour récupérer un champ à partir d’un enregistrement tant qu’aucune autre fonction, à l’exception de SQLGetDiagRec, SQLGetDiagField ou SQLError, n’a été appelée entre-temps. L’application peut également récupérer le nombre total d’enregistrements de diagnostic disponibles en appelant SQLGetDiagField pour récupérer la valeur du champ SQL_DIAG_NUMBER, puis en appelant SQLGetDiagRec plusieurs fois.

Pour obtenir une description des champs de la structure de données de diagnostic, consultez SQLGetDiagField. 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 de manière 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 désigne le type de handle de l’argument 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 » dans SQLGetDiagField.

Un appel à SQLGetDiagRec retourne SQL_INVALID_HANDLE si HandleType est SQL_HANDLE_SENV, ce qui désigne un handle d’environnement partagé. Toutefois, si HandleType est SQL_HANDLE_ENV, Handle peut être un handle d’environnement partagé ou non partagé.

Fonctions connexes

Voir aussi

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