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 « _ ». |
| 24 000 | É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