Fonction SQLPrepare

  • Article

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 de 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.)
01S02 Valeur de l’option modifiée Un attribut d’instruction spécifié n’étant pas valide en raison des conditions de travail d’implémentation, une valeur similaire a été temporairement remplacée. (SQLGetStmtAttr peut être appelé pour déterminer quelle est la valeur substituée temporairement.) La valeur de substitution 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 de la liaison de communication La liaison de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant que la fonction n’ait terminé le traitement.
21S01 Insérer une liste de valeurs 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 la table dérivée ne correspond pas à la liste de 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 contenant 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 élément 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 « LIKEpattern valueESCAPEescape 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 « _ ».
24 000 État de curseur non valide (DM) Un curseur était ouvert sur l’InstructionHandle et SQLFetchScroll avait été appelé.

Un curseur était ouvert sur l’InstructionHandle, mais SQLFetchScroll n’avait pas été appelé.
34000 Nom de curseur non valide *StatementText contenait un objet DELETE ou UPDATE positionné, et le curseur référencé par l’instruction en cours de préparation n’était pas ouvert.
3D000 Nom de 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 ne disposait pas des 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 table ou de 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 (référençant une table autre que celle en cours de création) 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 des noms de colonnes spécifiés dans la liste des 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 (référençant une table autre que celle en cours de création) n’existait pas.
HY000 Erreur générale Une erreur s’est produite pour laquelle il n’y avait pas de SQLSTATE spécifique et pour laquelle 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 la 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 l’InstructionHandle. La fonction a été appelée et, avant la fin de son 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 la fin de son exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un thread différent 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 exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. 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’InstructionHandle et a 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’InstructionHandle 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 a retourné SQL_NEED_DATA. Cette fonction a été appelée avant l’envoi des données pour toutes les colonnes ou paramètres de données au moment de 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, peut-être en raison de conditions de mémoire insuffisantes.
HY090 Chaîne ou longueur de mémoire tampon non valide (DM) L’argument TextLength était inférieur ou égal à 0, mais non é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 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é Le délai d’expiration a expiré avant que la source de données n’a retourné le jeu de résultats. Le délai d’expiration est défini via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Délai d’attente de la connexion expiré Le délai d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. Le délai d’expiration de connexion est défini via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Le pilote ne prend pas en charge cette fonction (DM) Le pilote associé à l’InstructionHandle 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 effectuer 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 le post-traitement et terminer l’opération.

Commentaires

L’application appelle SQLPrepare pour envoyer une instruction SQL à la source de données à des fins de 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ètres 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 d’instruction.

Notes

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 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 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 que l’application a préparé 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, uniquement les erreurs de syntaxe, ou ni les erreurs de syntaxe ni les violations d’accès. Par conséquent, une application doit être en mesure de 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 sur les paramètres (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 quand elle est exécutée (si tous les paramètres n’ont pas été liés). Pour une interopérabilité maximale, une application doit annuler la liaison de tous les paramètres appliqués à une ancienne instruction SQL avant de préparer une nouvelle instruction SQL sur la même instruction. Cela permet d’éviter les erreurs dues à l’application d’anciennes informations de paramètre à la nouvelle instruction.

Important

La validation d’une transaction, en appelant explicitement SQLEndTran ou 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 Effect of Transactions on Cursors and Prepared Statements.

Exemple de code

Consultez SQLBindParameter, SQLPutData et SQLSetPos.

Pour obtenir des 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 Fonction SQLBindCol
Liaison d’une mémoire tampon à un paramètre Fonction SQLBindParameter
Annulation du traitement des instructions SQLCancel, fonction
Exécution d’une opération de validation ou de restauration Fonction SQLEndTran
Exécution d’une instruction SQL SQLExecDirect, fonction
Exécution d’une instruction SQL préparée SQLExecute, fonction
Retour 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