SQLPrepare-Funktion
Konformität
Version eingeführt: ODBC 1.0-Normenkonformität: ISO 92
Zusammenfassung
SQLPrepare bereitet eine SQL-Zeichenfolge für die Ausführung vor.
Syntax
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Argumente
StatementHandle
[Eingabe] Anweisungshandle.
StatementText
[Eingabe] SQL-Textzeichenfolge.
TextLength
[Eingabe] Länge von *StatementText in Zeichen.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLPrepare SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLPrepare zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
| SQLSTATE | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S02 | Optionswert geändert | Ein angegebenes Anweisungsattribut war aufgrund der Arbeitsbedingungen der Implementierung ungültig, sodass ein ähnlicher Wert vorübergehend ersetzt wurde. (SQLGetStmtAttr kann aufgerufen werden, um zu bestimmen, was der vorübergehend ersetzte Wert ist.) Der Ersatzwert ist für statementHandle gültig, bis der Cursor geschlossen wird. Die Anweisungsattribute, die geändert werden können, sind: 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 (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 08S01 | Kommunikationslinkfehler | Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden war, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde. |
| 21S01 | Wertliste einfügen stimmt nicht mit Spaltenliste überein | *StatementText enthielt eine INSERT-Anweisung , und die Anzahl der einzufügenden Werte entsprach nicht dem Grad der abgeleiteten Tabelle. |
| 21S02 | Grad der abgeleiteten Tabelle stimmt nicht mit Spaltenliste überein | *StatementText enthielt eine CREATE VIEW-Anweisung , und die anzahl der angegebenen Namen entspricht nicht dem grad der abgeleiteten Tabelle, die durch die Abfragespezifikation definiert wurde. |
| 22018 | Ungültiger Zeichenwert für die Umwandlungsspezifikation | *StatementText enthielt eine SQL-Anweisung, die ein Literal oder einen Parameter enthielt, und der Wert war mit dem Datentyp der zugeordneten Tabellenspalte nicht kompatibel. |
| 22019 | Ungültiges Escapezeichen | Das Argument StatementText enthielt ein LIKE-Prädikat mit einem ESCAPE in der WHERE-Klausel , und die Länge des Escapezeichens nach ESCAPE war nicht gleich 1. |
| 22025 | Ungültige Escapesequenz | Das Argument StatementText enthielt "LIKE-MusterwertESCAPE-Escapezeichen" in der WHERE-Klausel, und das Zeichen nach dem Escapezeichen im Musterwert war weder "%" noch "_". |
| 24.000 | Ungültiger Cursorstatus | (DM) Ein Cursor war auf dem StatementHandle geöffnet, und SQLFetch oder SQLFetchScroll wurde aufgerufen. Im StatementHandle war ein Cursor geöffnet, aber SQLFetch oder SQLFetchScroll wurden nicht aufgerufen. |
| 34000 | Ungültiger Cursorname | *StatementText enthielt ein positioniertes DELETE oder ein positioniertes UPDATE, und der Cursor, auf den die vorbereitete Anweisung verweist, war nicht geöffnet. |
| 3D000 | Ungültiger Katalogname | Der in StatementText angegebene Katalogname war ungültig. |
| 3F000 | Ungültiger Schemaname | Der in StatementText angegebene Schemaname war ungültig. |
| 42000 | Syntaxfehler oder Zugriffsverletzung | *StatementText enthielt eine SQL-Anweisung, die nicht vorparierbar war oder einen Syntaxfehler enthielt. *StatementText enthielt eine Anweisung, für die der Benutzer nicht über die erforderlichen Berechtigungen verfügte. |
| 42S01 | Basistabelle oder -ansicht bereits vorhanden | *StatementText enthielt eine CREATE TABLE- oder CREATE VIEW-Anweisung , und der angegebene Tabellen- oder Ansichtsname ist bereits vorhanden. |
| 42S02 | Basistabelle oder -ansicht nicht gefunden | *StatementText enthielt eine DROP TABLE - oder DROP VIEW-Anweisung , und der angegebene Tabellen- oder Ansichtsname war nicht vorhanden. *StatementText enthielt eine ALTER TABLE-Anweisung , und der angegebene Tabellenname war nicht vorhanden. *StatementText enthielt eine CREATE VIEW-Anweisung , und ein durch die Abfragespezifikation definierter Tabellen- oder Ansichtsname war nicht vorhanden. *StatementText enthielt eine CREATE INDEX-Anweisung , und der angegebene Tabellenname war nicht vorhanden. *StatementText enthielt eine GRANT- oder REVOKE-Anweisung, und der angegebene Tabellen- oder Ansichtsname war nicht vorhanden. *StatementText enthielt eine SELECT-Anweisung , und ein angegebener Tabellen- oder Ansichtsname war nicht vorhanden. *StatementText enthielt eine DELETE-, INSERT- oder UPDATE-Anweisung, und der angegebene Tabellenname war nicht vorhanden. *StatementText enthielt eine CREATE TABLE-Anweisung , und eine Tabelle, die in einer Einschränkung angegeben wurde (die auf eine andere Tabelle als die erstellte verweist) war nicht vorhanden. |
| 42S11 | Index bereits vorhanden | *StatementText enthielt eine CREATE INDEX-Anweisung , und der angegebene Indexname war bereits vorhanden. |
| 42S12 | Index nicht gefunden | *StatementText enthielt eine DROP INDEX-Anweisung , und der angegebene Indexname war nicht vorhanden. |
| 42S21 | Spalte bereits vorhanden | *StatementText enthielt eine ALTER TABLE-Anweisung , und die in der ADD-Klausel angegebene Spalte ist nicht eindeutig oder identifiziert eine vorhandene Spalte in der Basistabelle. |
| 42S22 | Spalte nicht gefunden | *StatementText enthielt eine CREATE INDEX-Anweisung , und einer oder mehrere der in der Spaltenliste angegebenen Spaltennamen waren nicht vorhanden. *StatementText enthielt eine GRANT- oder REVOKE-Anweisung, und ein angegebener Spaltenname war nicht vorhanden. *StatementText enthielt eine SELECT-, DELETE-, INSERT- oder UPDATE-Anweisung, und ein angegebener Spaltenname war nicht vorhanden. *StatementText enthielt eine CREATE TABLE-Anweisung , und eine Spalte, die in einer Einschränkung angegeben wurde (die auf eine andere Als die erstellte Tabelle verweist) war nicht vorhanden. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist. |
| HY008 | Vorgang abgebrochen | Für statementHandle wurde die asynchrone Verarbeitung aktiviert. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle aufgerufen, und dann wurde die Funktion für die StatementHandle erneut aufgerufen. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle auf der StatementHandle von einem anderen Thread in einer Multithreadanwendung aufgerufen. |
| HY009 | Ungültige Verwendung von NULL-Zeiger | (DM) StatementText war ein NULL-Zeiger. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die SQLPrepare-Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für statementHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. (DM) Eine asynchron ausgeführte Funktion (nicht diese Funktion) wurde für das StatementHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für die StatementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführung gesendet wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | (DM) Das Argument TextLength war kleiner oder gleich 0, aber nicht gleich SQL_NTS. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum Angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYC00 | Optionale Funktion nicht implementiert | Die Parallelitätseinstellung war für den definierten Cursortyp ungültig. Das SQL_ATTR_USE_BOOKMARKS-Anweisungsattribut wurde auf SQL_UB_VARIABLE festgelegt, und das Attribut SQL_ATTR_CURSOR_TYPE-Anweisung wurde auf einen Cursortyp festgelegt, für den der Treiber keine Lesezeichen unterstützt. |
| HYT00 | Timeout abgelaufen | Der Timeoutzeitraum ist abgelaufen, bevor die Datenquelle das Resultset zurückgegeben hat. Der Timeoutzeitraum wird über SQLSetStmtAttr festgelegt, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitraum für das Verbindungstimeout wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Der Treiber unterstützt diese Funktion nicht. | (DM) Der der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM017 | Die Abfrage ist im asynchronen Benachrichtigungsmodus deaktiviert. | Wenn das Benachrichtigungsmodell verwendet wird, ist die Abfrage deaktiviert. |
| IM018 | SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen. | Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachverarbeitung durchzuführen und den Vorgang abzuschließen. |
Kommentare
Die Anwendung ruft SQLPrepare auf, um eine SQL-Anweisung zur Vorbereitung an die Datenquelle zu senden. Weitere Informationen zur vorbereiteten Ausführung finden Sie unter Vorbereitete Ausführung. Die Anwendung kann mindestens einen Parametermarker in der SQL-Anweisung enthalten. Um einen Parametermarker einzuschließen, bettet die Anwendung ein Fragezeichen (?) an der entsprechenden Position in die SQL-Zeichenfolge ein. Informationen zu Parametern finden Sie unter Anweisungsparameter.
Hinweis
Wenn eine Anwendung SQLPrepare zum Vorbereiten und SQLExecute zum Übermitteln einer COMMIT- oder ROLLBACK-Anweisung verwendet, ist sie nicht interoperabel zwischen DBMS-Produkten. Rufen Sie SQLEndTran auf, um eine Transaktion zu committen oder ein Rollback auszuführen.
Der Treiber kann die Anweisung so ändern, dass sie die von der Datenquelle verwendete SQL-Form verwendet, und sie dann zur Vorbereitung an die Datenquelle übermitteln. Insbesondere ändert der Treiber die Escapesequenzen, die zum Definieren der SQL-Syntax für bestimmte Features verwendet werden. (Eine Beschreibung der Grammatik der SQL-Anweisung finden Sie unter Escapesequenzen in ODBC und Anhang C: SQL-Grammatik.) Für den Treiber ähnelt ein Anweisungshandle einem Anweisungsbezeichner im eingebetteten SQL-Code. Wenn die Datenquelle Anweisungsbezeichner unterstützt, kann der Treiber einen Anweisungsbezeichner und Parameterwerte an die Datenquelle senden.
Nachdem eine Anweisung vorbereitet wurde, verwendet die Anwendung das Anweisungshandle, um in späteren Funktionsaufrufen auf die Anweisung zu verweisen. Die dem Anweisungshandle zugeordnete vorbereitete Anweisung kann durch Aufrufen von SQLExecute erneut ausgeführt werden, bis die Anwendung die Anweisung mit einem Aufruf von SQLFreeStmt mit der Option SQL_DROP freigibt oder bis das Anweisungshandle in einem Aufruf von SQLPrepare, SQLExecDirect oder einer der Katalogfunktionen (SQLColumns, SQLTables usw.) verwendet wird. Sobald die Anwendung eine Anweisung vorbereitet hat, kann sie Informationen zum Format des Resultsets anfordern. Bei einigen Implementierungen ist das Aufrufen von SQLDescribeCol oder SQLDescribeParam nach SQLPrepare möglicherweise nicht so effizient wie das Aufrufen der Funktion nach SQLExecute oder SQLExecDirect.
Einige Treiber können keine Syntaxfehler oder Zugriffsverletzungen zurückgeben, wenn die Anwendung SQLPrepare aufruft. Ein Treiber kann Syntaxfehler und Zugriffsverletzungen, nur Syntaxfehler oder Weder Syntaxfehler noch Zugriffsverletzungen behandeln. Daher muss eine Anwendung diese Bedingungen beim Aufrufen nachfolgender verwandter Funktionen wie SQLNumResultCols, SQLDescribeCol, SQLColAttribute und SQLExecute verarbeiten können.
Abhängig von den Funktionen des Treibers und der Datenquelle können Parameterinformationen (z. B. Datentypen) überprüft werden, wenn die Anweisung vorbereitet ist (wenn alle Parameter gebunden wurden) oder wenn sie ausgeführt wird (wenn alle Parameter nicht gebunden wurden). Um maximale Interoperabilität zu gewährleisten, sollte eine Anwendung alle Parameter aufheben, die auf eine alte SQL-Anweisung angewendet wurden, bevor sie eine neue SQL-Anweisung für dieselbe Anweisung vorbereitet. Dadurch werden Fehler verhindert, die darauf zurückzuführen sind, dass alte Parameterinformationen auf die neue Anweisung angewendet werden.
Wichtig
Das Committen einer Transaktion, entweder durch explizites Aufrufen von SQLEndTran oder durch Arbeiten im Autocommit-Modus, kann dazu führen, dass die Datenquelle die Zugriffspläne für alle Anweisungen für eine Verbindung löscht. Weitere Informationen finden Sie unter SQL_CURSOR_COMMIT_BEHAVIOR und SQL_CURSOR_ROLLBACK_BEHAVIOR Informationstypen in SQLGetInfo und Auswirkung von Transaktionen auf Cursor und vorbereitete Anweisungen.
Codebeispiel
Siehe SQLBindParameter, SQLPutData und SQLSetPos.
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Zuweisen eines Anweisungshandles | SQLAllocHandle-Funktion |
| Binden eines Puffers an eine Spalte in einem Resultset | SQLBindCol-Funktion |
| Binden eines Puffers an einen Parameter | SQLBindParameter-Funktion |
| Abbrechen der Anweisungsverarbeitung | SQLCancel-Funktion |
| Ausführen eines Commit- oder Rollbackvorgangs | SQLEndTran-Funktion |
| Ausführen einer SQL-Anweisung | SQLExecDirect-Funktion |
| Ausführen einer vorbereiteten SQL-Anweisung | SQLExecute-Funktion |
| Zurückgeben der Anzahl von Zeilen, die von einer Anweisung betroffen sind | SQLRowCount-Funktion |
| Festlegen eines Cursornamens | SQLSetCursorName-Funktion |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für