SQLNativeSql, fonction
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ODBC
Résumé
SQLNativeSql retourne la chaîne SQL telle qu’elle a été modifiée par le pilote. SQLNativeSql n’exécute pas l’instruction SQL.
Syntaxe
SQLRETURN SQLNativeSql(
SQLHDBC ConnectionHandle,
SQLCHAR * InStatementText,
SQLINTEGER TextLength1,
SQLCHAR * OutStatementText,
SQLINTEGER BufferLength,
SQLINTEGER * TextLength2Ptr);
Arguments
ConnectionHandle
[Entrée] Handle de connexion.
InStatementText
[Entrée] Chaîne de texte SQL à traduire.
TextLength1
[Entrée] Longueur en caractères de la chaîne de texte *InStatementText .
OutStatementText
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la chaîne SQL traduite.
Si OutStatementText est NULL, TextLength2Ptr retourne toujours le nombre total de caractères (à l’exclusion du caractère de terminaison Null pour les données de caractères) disponibles pour retourner dans la mémoire tampon indiquée par OutStatementText.
BufferLength
[Entrée] Nombre de caractères dans la mémoire tampon *OutStatementText . Les versions antérieures de cette documentation impliquent par erreur que ce nombre de caractères doit être même si la valeur retournée dans *InStatementText est une chaîne Unicode (lors de l’appel de SQLNativeSqlW). Il n’y a pas de telle restriction. Pour une interopérabilité optimale, les enregistreurs de pilotes doivent s’attendre à ce nombre de caractères transmis à cette fonction, tandis que les enregistreurs d’applications sont recommandés d’utiliser toujours un nombre pair.
TextLength2Ptr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total de caractères (à l’exception de l’arrêt null) disponibles pour retourner dans *OutStatementText. Si le nombre de caractères disponibles pour retourner est supérieur ou égal à BufferLength, la chaîne SQL traduite dans *OutStatementText est tronquée en BufferLength moins la longueur d’un caractère de terminaison Null.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Lorsque SQLNativeSql retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_DBC et un handle de ConnectionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLNativeSql et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions des SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Avertissement général | Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01004 | Données de chaîne, tronquées à droite | La mémoire tampon *OutStatementText n’était pas suffisamment grande pour renvoyer l’intégralité de la chaîne SQL, de sorte que la chaîne SQL a été tronquée. La longueur de la chaîne SQL nontruncée est retournée dans *TextLength2Ptr. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 08003 | Connexion non ouverte | ConnectionHandle n’était pas dans un état connecté. |
| 08S01 | Échec du lien de communication | Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant l’achèvement du traitement de la fonction. |
| 22007 | Format datetime non valide | *InStatementText contenait une clause d’échappement avec une valeur de date, d’heure ou d’horodatage non valide. |
| 24 000 | État de curseur non valide | Le curseur référencé dans l’instruction a été positionné avant le début du jeu de résultats ou après la fin du jeu de résultats. Cette erreur peut ne pas être retournée par un pilote ayant une implémentation de curseur SGBD native. |
| HY000 | Erreur générale | Une erreur s’est produite pour laquelle il n’y avait aucun SQLSTATE spécifique et pour lequel aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans la mémoire tampon *MessageText décrit l’erreur et sa cause. |
| HY001 | Erreur d’allocation de mémoire | Le pilote n’a pas pu allouer de mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction. |
| HY009 | Utilisation non valide du pointeur Null | (DM) *InStatementText était un pointeur Null. |
| HY010 | Erreur de séquence de fonction | (DM) Une fonction en cours d’exécution asynchrone a été appelée pour connectionHandle et était toujours en cours d’exécution lors de l’appel de cette fonction. |
| HY013 | Erreur de gestion de la mémoire | L’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’ont pas pu être accessibles, éventuellement en raison de conditions de mémoire insuffisantes. |
| HY090 | Longueur de la chaîne ou de la mémoire tampon non valide | (DM) L’argument TextLength1 était inférieur à 0, mais pas égal à SQL_NTS. |
| (DM) L’argument BufferLength était inférieur à 0 et l’argument OutStatementText n’était pas un pointeur Null. | ||
| HY109 | Position du curseur non valide | La ligne actuelle du curseur a été supprimée ou n’avait pas été récupérée. Cette erreur peut ne pas être retournée par un pilote ayant une implémentation de curseur SGBD native. |
| HY117 | La connexion est suspendue en raison d’un état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées. | (DM) Pour plus d’informations sur l’état suspendu, consultez la fonction SQLEndTran. |
| HYT01 | Délai d’attente de la connexion expiré | La période d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. La période d’expiration de connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote associé à ConnectionHandle ne prend pas en charge la fonction. |
Commentaires
Voici des exemples de ce que SQLNativeSql peut retourner pour la chaîne SQL d’entrée suivante contenant la fonction scalaire CONVERT. Supposons que l’empid de colonne est de type INTEGER dans la source de données :
SELECT { fn CONVERT (empid, SQL_SMALLINT) } FROM employee
Un pilote pour Microsoft SQL Server peut retourner la chaîne SQL traduite suivante :
SELECT convert (smallint, empid) FROM employee
Un pilote pour ORACLE Server peut retourner la chaîne SQL traduite suivante :
SELECT to_number (empid) FROM employee
Un pilote pour Ingres peut retourner la chaîne SQL traduite suivante :
SELECT int2 (empid) FROM employee
Pour plus d’informations, consultez Exécution directe et exécution préparée.
Fonctions connexes
Aucun.
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC