Fonction SQLPrepare

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

Résumé
SQLPrepare prépare une chaîne SQL pour l’exécution.

Syntaxe

  
SQLRETURN SQLPrepare(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     StatementText,  
     SQLINTEGER    TextLength);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

StatementText
[Entrée] Chaîne de texte SQL.

TextLength
[Entrée] Longueur de *StatementText en caractères.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLPrepare 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_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLPrepare 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	Erreur	Description
01000	Avertissement général	Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
01S02	Valeur d’option modifiée	Un attribut d’instruction spécifié n’était pas valide en raison de conditions de travail d’implémentation. Par conséquent, une valeur similaire a été temporairement remplacée. (SQLGetStmtAttr peut être appelé pour déterminer la valeur temporairement substituée.) La valeur de remplacement est valide pour l’InstructionHandle jusqu’à ce que le curseur soit fermé. Les attributs d’instruction qui peuvent être modifiés sont les suivants : SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_TYPE SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_SIMULATE_CURSOR (La fonction retourne SQL_SUCCESS_WITH_INFO.)
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.
21S01	La liste des valeurs d’insertion ne correspond pas à la liste de colonnes	*StatementText contenait une instruction INSERT et le nombre de valeurs à insérer ne correspondait pas au degré de la table dérivée.
21S02	Le degré de table dérivée ne correspond pas à la liste des colonnes	*StatementText contenait une instruction CREATE VIEW et le nombre de noms spécifiés n’est pas le même degré que la table dérivée définie par la spécification de requête.
22018	Valeur de caractère non valide pour la spécification de cast	*StatementText contenait une instruction SQL qui contenait un littéral ou un paramètre, et la valeur était incompatible avec le type de données de la colonne de table associée.
22019	Caractère d’échappement non valide	L’argument StatementText contenait un prédicat LIKE avec un ESCAPE dans la clause WHERE , et la longueur du caractère d’échappement suivant ESCAPE n’était pas égale à 1.
22025	Séquence d’échappement non valide	L’argument StatementText contenait « LIKE pattern value ESCAPE character » dans la clause WHERE, et le caractère suivant le caractère d’échappement dans la valeur de modèle n’était ni « % » ni « _ ».
24000	État de curseur non valide	(DM) Un curseur a été ouvert sur StatementHandle, et SQLFetch ou SQLFetchScroll avait été appelé. Un curseur a été ouvert sur StatementHandle, mais SQLFetch ou SQLFetchScroll n’avait pas été appelé.
34000	Nom de curseur non valide	*StatementText contenait une position DELETE ou une mise à jour positionnée, et le curseur référencé par l’instruction en cours de préparation n’était pas ouvert.
3D000	Nom du catalogue non valide	Le nom du catalogue spécifié dans StatementText n’était pas valide.
3F000	Nom de schéma non valide	Le nom de schéma spécifié dans StatementText n’était pas valide.
42000	Erreur de syntaxe ou violation d’accès	*StatementText contenait une instruction SQL qui n’était pas préparable ou contenait une erreur de syntaxe. *StatementText contenait une instruction pour laquelle l’utilisateur n’avait pas les privilèges requis.
42S01	La table ou la vue de base existe déjà	*StatementText contenait une instruction CREATE TABLE ou CREATE VIEW , et le nom de la table ou de la vue spécifié existe déjà.
42S02	Table de base ou vue introuvable	*StatementText contenait une instruction DROP TABLE ou DROP VIEW , et le nom de table ou de vue spécifié n’existait pas. *StatementText contenait une instruction ALTER TABLE et le nom de table spécifié n’existait pas. *StatementText contenait une instruction CREATE VIEW et un nom de table ou de vue défini par la spécification de requête n’existait pas. *StatementText contenait une instruction CREATE INDEX et le nom de table spécifié n’existait pas. *StatementText contenait une instruction GRANT ou REVOKE , et le nom de table ou de vue spécifié n’existait pas. *StatementText contenait une instruction SELECT et un nom de table ou de vue spécifié n’existait pas. *StatementText contenait une instruction DELETE, INSERT ou UPDATE , et le nom de table spécifié n’existait pas. *StatementText contenait une instruction CREATE TABLE et une table spécifiée dans une contrainte (faisant référence à une table autre que celle créée) n’existait pas.
42S11	L’index existe déjà	*StatementText contenait une instruction CREATE INDEX et le nom d’index spécifié existait déjà.
42S12	Index introuvable	*StatementText contenait une instruction DROP INDEX et le nom d’index spécifié n’existait pas.
42S21	La colonne existe déjà	*StatementText contenait une instruction ALTER TABLE , et la colonne spécifiée dans la clause ADD n’est pas unique ou identifie une colonne existante dans la table de base.
42S22	Colonne introuvable	*StatementText contenait une instruction CREATE INDEX , et un ou plusieurs noms de colonnes spécifiés dans la liste de colonnes n’existaient pas. *StatementText contenait une instruction GRANT ou REVOKE , et un nom de colonne spécifié n’existait pas. *StatementText contenait une instruction SELECT, DELETE, INSERT ou UPDATE , et un nom de colonne spécifié n’existait pas. *StatementText contenait une instruction CREATE TABLE et une colonne spécifiée dans une contrainte (faisant référence à une table autre que celle créée) n’existait pas.
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.
HY008	Opération annulée	Le traitement asynchrone a été activé pour StatementHandle. La fonction a été appelée, et avant qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle, puis la fonction a été appelée à nouveau sur l’InstructionHandle. La fonction a été appelée et avant qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle à partir d’un autre thread dans une application multithread.
HY009	Utilisation non valide du pointeur Null	(DM) StatementText é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 le handle de connexion associé à StatementHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLPrepare a été appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle et retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés en continu. (DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour l’instruction StatementHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’instructionHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à l’exécution.
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 TextLength était inférieur ou égal à 0, mais pas égal à SQL_NTS.
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.
HYC00	Fonctionnalité facultative non implémentée	Le paramètre d’accès concurrentiel n’était pas valide pour le type de curseur défini. L’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_VARIABLE, et l’attribut d’instruction SQL_ATTR_CURSOR_TYPE a été défini sur un type de curseur pour lequel le pilote ne prend pas en charge les signets.
HYT00	Délai expiré	La période d’expiration a expiré avant que la source de données ne retourne le jeu de résultats. La période d’expiration est définie via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
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é à StatementHandle ne prend pas en charge la fonction.
IM017	L’interrogation est désactivée en mode de notification asynchrone	Chaque fois que le modèle de notification est utilisé, l’interrogation est désactivée.
IM018	SQLCompleteAsync n’a pas été appelé pour terminer l’opération asynchrone précédente sur ce handle.	Si l’appel de fonction précédent sur le handle retourne SQL_STILL_EXECUTING et si le mode de notification est activé, SQLCompleteAsync doit être appelé sur le handle pour effectuer un post-traitement et terminer l’opération.

Commentaires

L’application appelle SQLPrepare pour envoyer une instruction SQL à la source de données pour la préparation. Pour plus d’informations sur l’exécution préparée, consultez Exécution préparée. L’application peut inclure un ou plusieurs marqueurs de paramètre dans l’instruction SQL. Pour inclure un marqueur de paramètre, l’application incorpore un point d’interrogation ( ?) dans la chaîne SQL à la position appropriée. Pour plus d’informations sur les paramètres, consultez Paramètres de l’instruction.

Remarque

Si une application utilise SQLPrepare pour préparer et SQLExecute pour envoyer une instruction COMMIT ou ROLLBACK , elle ne sera pas interopérable entre les produits SGBD. Pour valider ou restaurer une transaction, appelez SQLEndTran.

Le pilote peut modifier l’instruction pour utiliser la forme sql utilisée par la source de données, puis la soumettre à la source de données pour la préparation. En particulier, le pilote modifie les séquences d’échappement utilisées pour définir la syntaxe SQL pour certaines fonctionnalités. (Pour obtenir une description de la grammaire des instructions SQL, consultez Séquences d’échappement dans ODBC et l’annexe C : grammaire SQL.) Pour le pilote, un handle d’instruction est similaire à un identificateur d’instruction dans le code SQL incorporé. Si la source de données prend en charge les identificateurs d’instruction, le pilote peut envoyer un identificateur d’instruction et des valeurs de paramètre à la source de données.

Une fois qu’une instruction est préparée, l’application utilise le handle d’instruction pour faire référence à l’instruction dans les appels de fonction ultérieurs. L’instruction préparée associée au handle d’instruction peut être réexécutée en appelant SQLExecute jusqu’à ce que l’application libère l’instruction avec un appel à SQLFreeStmt avec l’option SQL_DROP ou jusqu’à ce que le handle d’instruction soit utilisé dans un appel à SQLPrepare, SQLExecDirect ou l’une des fonctions de catalogue (SQLColumns, SQLTables, etc.). Une fois l’application préparée une instruction, elle peut demander des informations sur le format du jeu de résultats. Pour certaines implémentations, l’appel de SQLDescribeCol ou SQLDescribeParam après SQLPrepare peut ne pas être aussi efficace que l’appel de la fonction après SQLExecute ou SQLExecDirect.

Certains pilotes ne peuvent pas retourner des erreurs de syntaxe ou des violations d’accès lorsque l’application appelle SQLPrepare. Un pilote peut gérer les erreurs de syntaxe et les violations d’accès, seules les erreurs de syntaxe, ni les erreurs de syntaxe ni les violations d’accès. Par conséquent, une application doit pouvoir gérer ces conditions lors de l’appel de fonctions connexes suivantes telles que SQLNumResultCols, SQLDescribeCol, SQLColAttribute et SQLExecute.

Selon les fonctionnalités du pilote et de la source de données, les informations de paramètre (telles que les types de données) peuvent être vérifiées lorsque l’instruction est préparée (si tous les paramètres ont été liés) ou lorsqu’elle est exécutée (si tous les paramètres n’ont pas été liés). Pour une interopérabilité maximale, une application doit dissocier tous les paramètres appliqués à une ancienne instruction SQL avant de préparer une nouvelle instruction SQL sur la même instruction. Cela empêche les erreurs dues aux anciennes informations de paramètre appliquées à la nouvelle instruction.

Important

La validation d’une transaction, soit en appelant explicitement SQLEndTran , soit en travaillant en mode de validation automatique, peut entraîner la suppression des plans d’accès pour toutes les instructions d’une connexion. Pour plus d’informations, consultez les types d’informations SQL_CURSOR_COMMIT_BEHAVIOR et SQL_CURSOR_ROLLBACK_BEHAVIOR dans SQLGetInfo et l’effet des transactions sur les curseurs et les instructions préparées.

Exemple de code

Consultez SQLBindParameter, SQLPutData et SQLSetPos.

Fonctions connexes

Pour plus d’informations sur	Consultez
Allocation d’un handle d’instruction	SQLAllocHandle, fonction
Liaison d’une mémoire tampon à une colonne dans un jeu de résultats	SQLBindCol, fonction
Liaison d’une mémoire tampon à un paramètre	SQLBindParameter, fonction
Annulation du traitement des instructions	SQLCancel, fonction
Exécution d’une opération de validation ou de restauration	SQLEndTran, fonction
Exécution d’une instruction SQL	SQLExecDirect, fonction
Exécution d’une instruction SQL préparée	SQLExecute, fonction
Renvoi du nombre de lignes affectées par une instruction	SQLRowCount, fonction
Définition d’un nom de curseur	SQLSetCursorName, fonction

Voir aussi

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