Freigeben über


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.

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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien