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