Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Conformiteit
Versie geïntroduceerd: NALEVING van ODBC 1.0-standaarden: ISO 92
Samenvatting
SQLPrepare bereidt een SQL-string voor voor uitvoering.
Syntax
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Arguments
StatementHandle
[Invoer] Instructiehandgreep.
StatementText
[Invoer] SQL-tekststring.
TextLength
[Invoer] Lengte van *StatementText in tekens.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR of SQL_INVALID_HANDLE.
Diagnostics
Wanneer SQLPrepare SQL_ERROR of SQL_SUCCESS_WITH_INFO teruggeeft, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec aan te roepen met een HandleType van SQL_HANDLE_STMT en een Handle van StatementHandle. De volgende tabel geeft een overzicht van de SQLSTATE-waarden die vaak door SQLPrepare worden geretourneerd en legt elk uit in de context van deze functie; de notatie "(DM)" gaat vooraf aan de beschrijvingen van SQLSTATES die door de Driver Manager worden teruggegeven. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.
| SQLSTATE | Fout | Description |
|---|---|---|
| 01000 | Algemene waarschuwing | Stuurprogrammaspecifiek informatiebericht. (Functie retourneert SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Optiewaarde gewijzigd | Een opgegeven instructiekenmerk is ongeldig vanwege de arbeidsomstandigheden van de implementatie, dus een vergelijkbare waarde is tijdelijk vervangen. (SQLGetStmtAttr kan worden aangeroepen om te bepalen wat de tijdelijk gesubstitueerde waarde is.) De vervangingswaarde is geldig voor de StatementHandle totdat de cursor wordt gesloten. De statementattributen die kunnen worden gewijzigd zijn: 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 (Functie retourneert SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Communicatiekoppelingsfout | De communicatiekoppeling tussen het stuurprogramma en de gegevensbron waarmee het stuurprogramma is verbonden, is mislukt voordat de verwerking van de functie is voltooid. |
| 21S01 | Lijst met waarden invoegen komt niet overeen met de kolomlijst | * StatementText bevatte een INSERT statement, en het aantal in te voegen waarden kwam niet overeen met de graad van de afgeleide tabel. |
| 21S02 | De mate van afgeleide tabel komt niet overeen met de kolomlijst | * StatementText bevatte een CREATE VIEW statement, en het aantal gespecificeerde namen is niet dezelfde graad als de afgeleide tabel die door de queryspecificatie wordt gedefinieerd. |
| 22018 | Ongeldige tekenwaarde voor cast-specificatie | * StatementText bevatte een SQL-instructie die een literal of parameter bevatte, en de waarde was niet compatibel met het datatype van de bijbehorende kolom in de tabel. |
| 22019 | Ongeldig escape-teken | Het argument StatementText bevatte een LIKE-predicaat met een ESCAPE in de WHERE-clausule, en de lengte van het escape-teken na ESCAPE was niet gelijk aan 1. |
| 22025 | Ongeldige escapereeks | Het argument StatementText bevatte "LIKEpattern valueESCAPEcharacter" in de WHERE-clausule, en het teken dat volgde op het escape-teken in de patroonwaarde was noch "%" noch "_". |
| 24000 | Ongeldige cursorstatus | (DM) Er stond een cursor open op de StatementHandle, en SQLFetch of SQLFetchScroll was aangeroepen. Er stond een cursor open op de StatementHandle, maar SQLFetch of SQLFetchScroll waren nog niet aangeroepen. |
| 34000 | Ongeldige cursornaam | * StatementText bevatte een gepositioneerde DELETE of een gepositioneerde UPDATE, en de cursor waarnaar werd verwezen door de te voorbereiden verklaring was niet open. |
| 3D000 | Ongeldige catalogusnaam | De catalogusnaam die is opgegeven in StatementText , is ongeldig. |
| 3F000 | Ongeldige schemanaam | De schemanaam die is opgegeven in StatementText , is ongeldig. |
| 42000 | Syntaxisfout of schending van toegang |
*
StatementText bevatte een SQL-instructie die niet preparable was of een syntaxisfout bevatte. * StatementText bevatte een instructie waarvoor de gebruiker niet de vereiste rechten had. |
| 42S01 | Basistabel of -weergave bestaat al | * StatementText bevatte een CREATE TABLE or-statement CREATE VIEW , en de gespecificeerde tabelnaam of weergavenaam bestaat al. |
| 42S02 | Basistabel of -weergave is niet gevonden |
*
StatementText bevatte een DROP TABLE of een DROP VIEW statement, en de gespecificeerde tabelnaam of weergavenaam bestond niet. * StatementText bevatte een ALTER TABLE instructie, en de opgegeven tabelnaam bestond niet. * StatementText bevatte een CREATE VIEW statement, en er bestond geen tabelnaam of weergavenaam die door de query-specificatie werd gedefinieerd. * StatementText bevatte een CREATE INDEX instructie, en de opgegeven tabelnaam bestond niet. * StatementText bevatte een GRANT or-instructie REVOKE , en de gespecificeerde tabelnaam of weergavenaam bestond niet. * StatementText bevatte een SELECT-instructie en een opgegeven tabelnaam of weergavenaam bestond niet. * StatementText bevatte een DELETE, INSERT, of UPDATE statement, en de gespecificeerde tabelnaam bestond niet. * StatementText bevatte een CREATE TABLE statement, en een tabel die in een constraint werd gespecificeerd (verwijzend naar een andere tabel dan de te maken is) bestond niet. |
| 42S11 | Index bestaat al | * StatementText bevatte een CREATE INDEX statement, en de gespecificeerde indexnaam bestond al. |
| 42S12 | Index is niet gevonden | * StatementText bevatte een DROP INDEX statement, en de gespecificeerde indexnaam bestond niet. |
| 42S21 | Kolom bestaat al | * StatementText bevatte een ALTER TABLE statement, en de kolom die in de ADD-clausule is gespecificeerd is niet uniek of identificeert een bestaande kolom in de basistabel. |
| 42S22 | Kolom is niet gevonden |
*
StatementText bevatte een CREATE INDEX statement, en een of meer van de kolomnamen die in de kolomlijst werden gespecificeerd, bestonden niet. * StatementText bevatte een GRANT or-statement REVOKE , en een gespecificeerde kolomnaam bestond niet. * StatementText bevatte een SELECT, DELETE, , INSERTof UPDATE statement, en een gespecificeerde kolomnaam bestond niet. * StatementText bevatte een CREATE TABLE statement, en een kolom die in een constraint was gespecificeerd (verwijzend naar een andere tabel dan de aangemaakte) bestond niet. |
| HY000 | Algemene fout | Er is een fout opgetreden waarvoor er geen specifieke SQLSTATE is en waarvoor geen implementatiespecifieke SQLSTATE is gedefinieerd. Het foutbericht dat door SQLGetDiagRec in de *MessageText-buffer wordt geretourneerd, beschrijft de fout en de oorzaak ervan. |
| HY001 | Fout bij geheugentoewijzing | Het stuurprogramma kan geen geheugen toewijzen dat nodig is om de uitvoering of voltooiing van de functie te ondersteunen. |
| HY008 | Bewerking geannuleerd | Asynchrone verwerking is ingeschakeld voor de StatementHandle. De functie werd aangeroepen, en voordat de uitvoering voltooid was, werd SQLCancel of SQLCancelHandle aangeroepen op de StatementHandle, en daarna werd de functie opnieuw aangeroepen op de StatementHandle. De functie is aangeroepen en voordat de uitvoering is voltooid, werd SQLCancel of SQLCancelHandle aangeroepen op de StatementHandle vanuit een andere thread in een multithread-toepassing. |
| HY009 | Ongeldig gebruik van null-aanwijzer | (DM) StatementText was een nullpointer. |
| HY010 | Fout in functiereeks | (DM) Er is een asynchroon uitgevoerde functie aangeroepen voor de verbindingsgreep die is gekoppeld aan de StatementHandle. Deze asynchrone functie was nog steeds in uitvoering toen de SQLPreparare-functie werd aangeroepen. (DM) SQLExecute, SQLExecDirect of SQLMoreResults werd aangeroepen voor de StatementHandle en geretourneerd SQL_PARAM_DATA_AVAILABLE. Deze functie is aangeroepen voordat gegevens zijn opgehaald voor alle gestreamde parameters. (DM) Er is een asynchroon uitgevoerde functie (niet deze) aangeroepen voor de StatementHandle en werd nog steeds uitgevoerd toen deze functie werd aangeroepen. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations of SQLSetPos werd aangeroepen voor de StatementHandle en geretourneerd SQL_NEED_DATA. Deze functie is aangeroepen voordat gegevens werden verzonden voor alle parameters of kolommen voor uitvoering van gegevens. |
| HY013 | Fout bij geheugenbeheer | De functie-aanroep kan niet worden verwerkt omdat de onderliggende geheugenobjecten niet kunnen worden geopend, mogelijk vanwege weinig geheugen. |
| HY090 | Ongeldige tekenreeks- of bufferlengte | (DM) Het argument TextLength was kleiner dan of gelijk aan 0, maar niet gelijk aan SQL_NTS. |
| HY117 | De verbinding is onderbroken vanwege een onbekende transactiestatus. Alleen de verbinding verbreken en alleen-lezenfuncties zijn toegestaan. | (DM) Zie SQLEndTran Function voor meer informatie over de onderbroken status. |
| HYC00 | Optionele functie niet geïmplementeerd | De gelijktijdigheidsinstelling was ongeldig voor het type cursor dat werd gedefinieerd. Het kenmerk SQL_ATTR_USE_BOOKMARKS instructie is ingesteld op SQL_UB_VARIABLE en het kenmerk SQL_ATTR_CURSOR_TYPE instructie is ingesteld op een cursortype waarvoor het stuurprogramma geen bladwijzers ondersteunt. |
| HYT00 | Time-out verlopen | De time-out periode verliep voordat de databron de resultaatset teruggaf. De time-outperiode wordt ingesteld via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Time-out voor de verbinding is overschreden | De time-outperiode voor de verbinding is verlopen voordat de gegevensbron op de aanvraag heeft gereageerd. De time-outperiode voor de verbinding wordt ingesteld via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Stuurprogramma biedt geen ondersteuning voor deze functie | (DM) Het stuurprogramma dat is gekoppeld aan de StatementHandle biedt geen ondersteuning voor de functie. |
| IM017 | Polling is uitgeschakeld in de asynchrone meldingsmodus | Wanneer het meldingsmodel wordt gebruikt, wordt polling uitgeschakeld. |
| IM018 | SQLCompleteAsync is niet aangeroepen om de vorige asynchrone bewerking op deze ingang te voltooien. | Als de vorige functieaanroep op de ingang SQL_STILL_EXECUTING retourneert en als de meldingsmodus is ingeschakeld, moet SQLCompleteAsync worden aangeroepen op de ingang om naverwerking te kunnen uitvoeren en de bewerking te voltooien. |
Comments
De applicatie roept SQLPrepare aan om een SQL-instructie naar de databron te sturen ter voorbereiding. Voor meer informatie over voorbereide uitvoering, zie Voorbereide uitvoering. De applicatie kan één of meer parametermarkers opnemen in de SQL-instructie. Om een parametermarker toe te voegen, voegt de applicatie een vraagteken (?) in de SQL-string in op de juiste positie. Zie Instructieparameters voor meer informatie over parameters.
Note
Als een applicatie SQLPrepare gebruikt om een COMMIT- of ROLLBACK-instructie voor te bereiden en SQLExecute een COMMIT- of ROLLBACK-instructie in te dienen, zal deze niet interoperabel zijn tussen DBMS-producten. Als u een transactie wilt doorvoeren of terugdraaien, roept u SQLEndTran aan.
De driver kan de instructie aanpassen om de vorm van SQL te gebruiken die door de databron wordt gebruikt en deze vervolgens naar de databron sturen ter voorbereiding. In het bijzonder wijzigt de driver de escape-sequenties die worden gebruikt om SQL-syntaxis voor bepaalde functies te definiëren. (Voor een beschrijving van SQL-instructiegrammatica, zie Escape Sequences in ODBC en Bijlage C: SQL Grammar.) Voor de driver lijkt een statementhandle op een statement-identificatie in embedded SQL-code. Als de databron statement-identifiers ondersteunt, kan de driver een statement-identifier en parameterwaarden naar de databron sturen.
Nadat een statement is voorbereid, gebruikt de applicatie de statementhandle om in latere functieaanroepen naar de statement te verwijzen. De voorbereide instructie die bij de statementhandle hoort, kan opnieuw worden uitgevoerd door SQLExecute aan te roepen totdat de applicatie de statement vrijmaakt met een aanroep naar SQLFreeStmt met de SQL_DROP-optie, of totdat de statementhandle wordt gebruikt in een aanroep naar SQLPrepare, SQLExecDirect of een van de catalogusfuncties (SQLColumns, SQLTables, enzovoort). Zodra de applicatie een statement heeft voorbereid, kan het informatie opvragen over het formaat van de resultaatset. Voor sommige implementaties is het aanroepen van SQLDescribeCol of SQLDescribeParam na SQLPrepare mogelijk minder efficiënt dan het aanroepen van de functie na SQLExecute of SQLExecDirect.
Sommige drivers kunnen geen syntaxisfouten of toegangsovertredingen teruggeven wanneer de applicatie SQLPrepare aanroept. Een driver kan syntaxisfouten en toegangsovertredingen afhandelen, alleen syntaxisfouten, of noch syntaxisfouten noch toegangsschendingen. Daarom moet een applicatie deze voorwaarden kunnen aankunnen bij het aanroepen van latere gerelateerde functies zoals SQLNumResultCols, SQLDescribeCol, SQLColAttribute en SQLExecute.
Afhankelijk van de mogelijkheden van de driver en databron kan parameterinformatie (zoals datatypes) worden gecontroleerd wanneer de instructie wordt voorbereid (als alle parameters zijn gebonden) of wanneer deze wordt uitgevoerd (als niet alle parameters zijn gebonden). Voor maximale interoperabiliteit moet een applicatie alle parameters die op een oude SQL-instructie van toepassing zijn loskoppelen voordat een nieuwe SQL-instructie op dezelfde instructie wordt voorbereid. Dit voorkomt fouten die ontstaan doordat oude parameterinformatie op de nieuwe instructie wordt toegepast.
Important
Het committen van een transactie, hetzij door expliciet SQLEndTran aan te roepen of door in autocommit-modus te werken, kan ertoe leiden dat de databron de toegangsplannen voor alle statements op een verbinding verwijdert. Voor meer informatie, zie de SQL_CURSOR_COMMIT_BEHAVIOR- en SQL_CURSOR_ROLLBACK_BEHAVIOR-informatietypen in SQLGetInfo en Effect van Transacties op cursors en voorbereide statements.
Codevoorbeeld
Zie SQLBindParameter, SQLPutData en SQLSetPos.
Gerelateerde functies
| Voor informatie over | Zien! |
|---|---|
| Toewijzen van een statementhandle | SQLAllocHandle-functie |
| Een buffer koppelen aan een kolom in een resultatenset | SQLBindCol, functie |
| Een buffer binden aan een parameter | SQLBindParameter-functie |
| Verwerking van instructie annuleren | SQLCancel, functie |
| Een doorvoer- of terugdraaibewerking uitvoeren | SQLEndTran, functie |
| Een SQL-instructie uitvoeren | SQLExecDirect-functie |
| Een voorbereide SQL-instructie uitvoeren | SQLExecute, functie |
| Het aantal rijen dat door een statement wordt beïnvloed teruggeven. | SQLRowCount-functie |
| Een cursornaam instellen | SQLSetCursorName, functie |