SQLPrepare-Funktion
Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: 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.
Diagnostik
Wenn SQLPrepare SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLPrepare zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
| SQLSTATE | Error | Beschreibung |
|---|---|---|
| 01000 | Allgemeiner Warnhinweis | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S02 | Optionswert geändert | Ein angegebenes Anweisungsattribut war aufgrund von Implementierungsbedingungen 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 das StatementHandle gültig, bis der Cursor geschlossen wird. Die zu ändernden Anweisungsattribute 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 (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 08S01 | Kommunikationslinkfehler | Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde. |
| 21S01 | Die Liste einzufügender Werte passt nicht zur Spaltenliste. | *StatementText enthielt eine INSERT-Anweisung , und die Anzahl der einzufügenden Werte entsprach nicht dem Grad der abgeleiteten Tabelle. |
| 21S02 | Der Grad der abgeleiteten Tabelle stimmt nicht mit der Spaltenliste überein. | *StatementText enthielt eine CREATE VIEW-Anweisung , und die angegebene Anzahl von Namen entspricht nicht dem Grad der abgeleiteten Tabelle, die von der 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 nicht mit dem Datentyp der zugeordneten Tabellenspalte 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 | The argument StatementText contained "LIKE pattern value ESCAPE escape character" in the WHERE clause, and the character following the escape character in the pattern value was weder "%" noch "_". |
| 24.000 | Ungültiger Cursorstatus | (DM) Ein Cursor wurde im StatementHandle geöffnet, und SQLFetch oder SQLFetchScroll wurden aufgerufen. Ein Cursor war für " StatementHandle" 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 ist 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 es ist kein Tabellen- oder Ansichtsname vorhanden, der von der Abfragespezifikation definiert wurde. *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 in einer Einschränkung angegebene Tabelle (die auf eine andere Tabelle als die erstellte verweist) war nicht vorhanden. |
| 42S11 | Index ist bereits vorhanden | *StatementText enthielt eine CREATE INDEX-Anweisung , und der angegebene Indexname ist bereits vorhanden. |
| 42S12 | Index nicht gefunden | *StatementText enthielt eine DROP INDEX-Anweisung , und der angegebene Indexname war nicht vorhanden. |
| 42S21 | Spalte ist 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 mindestens eine der in der Spaltenliste angegebenen Spaltennamen war 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 ist (verweisen auf eine andere Tabelle als die erstellte) ist nicht vorhanden. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und dessen Ursache. |
| HY001 | Speicherzuweisungsfehler | Der Treiber konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen. |
| HY008 | Vorgang abgebrochen | Die asynchrone Verarbeitung wurde für " StatementHandle" 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 erneut für "StatementHandle" aufgerufen. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle von einem anderen Thread in einer Multithreadanwendung aufgerufen. |
| HY009 | Ungültige Verwendung des Nullzeigers | (DM) StatementText war ein Nullzeiger. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungshandle aufgerufen, der 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) wurde für das StatementHandle aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für " StatementHandle " aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden. |
| HY013 | Speicherverwaltungsfehler | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen. |
| 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 des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function. |
| HYC00 | Optionales Feature wurde nicht implementiert | Die Parallelitätseinstellung war für den definierten Cursortyp ungültig. Das attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung wurde auf SQL_UB_VARIABLE festgelegt, und das Attribut der SQL_ATTR_CURSOR_TYPE-Anweisung wurde auf einen Cursortyp festgelegt, für den der Treiber keine Lesezeichen unterstützt. |
| HYT00 | Timeout überschritten | Der Timeoutzeitraum ist abgelaufen, bevor die Datenquelle das Resultset zurückgibt. Der Timeoutzeitraum wird über SQLSetStmtAttr SQL_ATTR_QUERY_TIMEOUT festgelegt. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt. |
| IM001 | Dieser Treiber unterstützt diese Funktion nicht. | (DM) Der dem StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM017 | Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert. | Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung 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 Nachbearbeitung 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 eine oder mehrere Parametermarkierungen in der SQL-Anweisung enthalten. Um eine Parametermarkierung 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 übernehmen oder ein Rollback durchzuführen.
Der Treiber kann die Anweisung ändern, um die Form von SQL zu verwenden, die von der Datenquelle verwendet wird, und sie dann zur Vorbereitung an die Datenquelle zu ü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 Grammar.) 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 auf die Anweisung in späteren Funktionsaufrufen zu verweisen. Die vorbereitete Anweisung, die dem Anweisungshandle zugeordnet ist, kann durch Aufrufen von SQLExecute erneut ausgeführt werden, bis die Anwendung die Anweisung mit einem Aufruf von SQLFreeStmt mit der Option SQL_DROP 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 werden Parameterinformationen (z. B. Datentypen) möglicherweise überprüft, wenn die Anweisung vorbereitet wird (wenn alle Parameter gebunden wurden) oder wenn sie ausgeführt wird (wenn alle Parameter nicht gebunden wurden). Für die maximale Interoperabilität sollte eine Anwendung alle Parameter aufheben, die auf eine alte SQL-Anweisung angewendet wurden, bevor Sie eine neue SQL-Anweisung für dieselbe Anweisung vorbereiten. Dadurch werden Fehler verhindert, die auf alte Parameterinformationen zurückzuführen sind, die auf die neue Anweisung angewendet werden.
Wichtig
Commit für eine 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 in den SQL_CURSOR_COMMIT_BEHAVIOR- und SQL_CURSOR_ROLLBACK_BEHAVIOR Informationstypen in SQLGetInfo und Auswirkungen von Transaktionen auf Cursor und vorbereitete Anweisungen.
Codebeispiel
Siehe SQLBindParameter, SQLPutData und SQLSetPos.
Verwandte Funktionen
| Weitere Informationen zu | Siehe |
|---|---|
| Zuordnen 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 Verarbeitung von Anweisungen | 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 |