Pagina relativa alla funzione SQLPrepare
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92
Riepilogo
SQLPrepare prepara una stringa SQL per l'esecuzione.
Sintassi
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Argomenti
StatementHandle
[Input] Handle di istruzione.
StatementText
[Input] Stringa di testo SQL.
TextLength
[Input] Lunghezza di *StatementText in caratteri.
Valori restituiti
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLPrepare restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleType di SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLPrepare e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| 01000 | Avviso generale | Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S02 | Valore dell'opzione modificato | Un attributo di istruzione specificato non è valido a causa delle condizioni di lavoro dell'implementazione, pertanto è stato sostituito temporaneamente un valore simile. È possibile chiamare SQLGetStmtAttr per determinare il valore sostituito temporaneamente. Il valore sostitutivo è valido per StatementHandle fino alla chiusura del cursore. Gli attributi dell'istruzione che possono essere modificati sono: 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 funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 08S01 | Errore del collegamento di comunicazione | Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione. |
| 21S01 | L'elenco di valori di inserimento non corrisponde all'elenco di colonne | *StatementText contiene un'istruzione INSERT e il numero di valori da inserire non corrisponde al grado della tabella derivata. |
| 21S02 | Il grado di tabella derivata non corrisponde all'elenco di colonne | *StatementText contiene un'istruzione CREATE VIEW e il numero di nomi specificati non corrisponde alla tabella derivata definita dalla specifica della query. |
| 22018 | Valore carattere non valido per la specifica del cast | *StatementText conteneva un'istruzione SQL contenente un valore letterale o un parametro e il valore non era compatibile con il tipo di dati della colonna di tabella associata. |
| 22019 | Carattere di escape non valido | L'argomento StatementText contiene un predicato LIKE con escape nella clausola WHERE e la lunghezza del carattere di escape seguente escape non è uguale a 1. |
| 22025 | Sequenza di escape non valida | L'argomento StatementText conteneva il carattere di escape ESCAPE del valore del criterio LIKE nella clausola WHERE e il carattere che segue il carattere di escape nel valore del criterio non era "%" né "_". |
| 24000 | Stato del cursore non valido | (DM) È stato aperto un cursore in StatementHandle e SQLFetch o SQLFetchScroll è stato chiamato. Un cursore è stato aperto in StatementHandle, ma SQLFetch o SQLFetchScroll non è stato chiamato. |
| 34000 | Nome di cursore non valido | *StatementText conteneva un'istruzione DELETE posizionata o un UPDATE posizionato e il cursore a cui fa riferimento l'istruzione preparata non era aperta. |
| 3D000 | Nome catalogo non valido | Il nome del catalogo specificato in StatementText non è valido. |
| 3F000 | Nome dello schema non valido | Il nome dello schema specificato in StatementText non è valido. |
| 42000 | Errore di sintassi o violazione di accesso | *StatementText conteneva un'istruzione SQL che non era preparabile o conteneva un errore di sintassi. *StatementText contiene un'istruzione per cui l'utente non dispone dei privilegi necessari. |
| 42S01 | Tabella o vista di base già esistente | *StatementText contiene un'istruzione CREATE TABLE o CREATE VIEW e il nome della tabella o della vista specificato esiste già. |
| 42S02 | Tabella o vista di base non trovata | *StatementText contiene un'istruzione DROP TABLE o DROP VIEW e il nome della tabella o della vista specificato non esisteva. *StatementText contiene un'istruzione ALTER TABLE e il nome della tabella specificato non esisteva. *StatementText contiene un'istruzione CREATE VIEW e un nome di tabella o vista definito dalla specifica della query non esisteva. *StatementText contiene un'istruzione CREATE INDEX e il nome della tabella specificato non esiste. *StatementText contiene un'istruzione GRANT o REVOKE e il nome della tabella o della vista specificato non esiste. *StatementText contiene un'istruzione SELECT e un nome di tabella o vista specificato non esisteva. *StatementText conteneva un'istruzione DELETE, INSERT o UPDATE e il nome della tabella specificato non esisteva. *StatementText contiene un'istruzione CREATE TABLE e una tabella specificata in un vincolo (che fa riferimento a una tabella diversa da quella creata) non esiste. |
| 42S11 | Indice già esistente | *StatementText contiene un'istruzione CREATE INDEX e il nome di indice specificato esiste già. |
| 42S12 | Indice non trovato | *StatementText conteneva un'istruzione DROP INDEX e il nome dell'indice specificato non esisteva. |
| 42S21 | Colonna già esistente | *StatementText contiene un'istruzione ALTER TABLE e la colonna specificata nella clausola ADD non è univoca o identifica una colonna esistente nella tabella di base. |
| 42S22 | Colonna non trovata | *StatementText contiene un'istruzione CREATE INDEX e uno o più nomi di colonna specificati nell'elenco di colonne non esistevano. *StatementText conteneva un'istruzione GRANT o REVOKE e un nome di colonna specificato non esisteva. *StatementText conteneva un'istruzione SELECT, DELETE, INSERT o UPDATE e un nome di colonna specificato non esisteva. *StatementText conteneva un'istruzione CREATE TABLE e una colonna specificata in un vincolo (facendo riferimento a una tabella diversa da quella creata) non esisteva. |
| HY000 | Errore generale: | Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa. |
| HY001 | Errore di allocazione della memoria | Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione. |
| HY008 | Operazione annullata | L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata su StatementHandle e quindi la funzione è stata chiamata nuovamente in StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread. |
| HY009 | Uso non valido del puntatore Null | (DM) StatementText era un puntatore Null. |
| HY010 | Errore della sequenza di funzioni | (DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata la funzione SQLPrepare . (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed è ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution. |
| HY013 | Errore di gestione della memoria | Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente. |
| HY090 | Lunghezza della stringa o del buffer non valida | (DM) L'argomento TextLength è minore o uguale a 0, ma non uguale a SQL_NTS. |
| HY117 | La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. | (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran. |
| HYC00 | Funzionalità facoltativa non implementata | L'impostazione della concorrenza non è valida per il tipo di cursore definito. L'attributo di istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_VARIABLE e l'attributo dell'istruzione SQL_ATTR_CURSOR_TYPE è stato impostato su un tipo di cursore per cui il driver non supporta i segnalibri. |
| HYT00 | Timeout scaduto | Periodo di timeout scaduto prima che l'origine dati restituisca il set di risultati. Il periodo di timeout viene impostato tramite SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Il timeout della connessione è scaduto | Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Il driver non supporta questa funzione | (DM) Il driver associato a StatementHandle non supporta la funzione. |
| IM017 | Il polling è disabilitato in modalità di notifica asincrona | Ogni volta che viene usato il modello di notifica, il polling è disabilitato. |
| IM018 | SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle. | Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione. |
Commenti
L'applicazione chiama SQLPrepare per inviare un'istruzione SQL all'origine dati per la preparazione. Per altre informazioni sull'esecuzione preparata, vedere Esecuzione preparata. L'applicazione può includere uno o più marcatori di parametro nell'istruzione SQL. Per includere un marcatore di parametro, l'applicazione incorpora un punto interrogativo (?) nella stringa SQL nella posizione appropriata. Per informazioni sui parametri, vedere Parametri delle istruzioni.
Nota
Se un'applicazione usa SQLPrepare per preparare e SQLExecute per inviare un'istruzione COMMIT o ROLLBACK , non sarà interoperabile tra i prodotti DBMS. Per eseguire il commit o il rollback di una transazione, chiamare SQLEndTran.
Il driver può modificare l'istruzione in modo da usare il formato SQL usato dall'origine dati e quindi inviarlo all'origine dati per la preparazione. In particolare, il driver modifica le sequenze di escape usate per definire la sintassi SQL per determinate funzionalità. Per una descrizione della grammatica dell'istruzione SQL, vedere Sequenze di escape in ODBC e Appendice C: Grammatica SQL. Per il driver, un handle di istruzione è simile a un identificatore di istruzione nel codice SQL incorporato. Se l'origine dati supporta gli identificatori di istruzione, il driver può inviare un identificatore di istruzione e i valori dei parametri all'origine dati.
Dopo la preparazione di un'istruzione, l'applicazione usa l'handle di istruzione per fare riferimento all'istruzione nelle chiamate di funzione successive. L'istruzione preparata associata all'handle di istruzione può essere eseguita nuovamente chiamando SQLExecute finché l'applicazione non libera l'istruzione con una chiamata a SQLFreeStmt con l'opzione SQL_DROP o fino a quando l'handle di istruzione non viene usato in una chiamata a SQLPrepare, SQLExecDirect o una delle funzioni del catalogo (SQLColumns, SQLTables e così via). Dopo aver preparato un'istruzione, l'applicazione può richiedere informazioni sul formato del set di risultati. Per alcune implementazioni, la chiamata a SQLDescribeCol o SQLDescribeParam dopo SQLPrepare potrebbe non essere efficiente come chiamare la funzione dopo SQLExecute o SQLExecDirect.
Alcuni driver non possono restituire errori di sintassi o violazioni di accesso quando l'applicazione chiama SQLPrepare. Un driver può gestire errori di sintassi e violazioni di accesso, solo errori di sintassi o né errori di sintassi né violazioni di accesso. Pertanto, un'applicazione deve essere in grado di gestire queste condizioni quando si chiamano funzioni correlate successive, ad esempio SQLNumResultCols, SQLDescribeCol, SQLColAttribute e SQLExecute.
A seconda delle funzionalità del driver e dell'origine dati, le informazioni sui parametri (ad esempio i tipi di dati) potrebbero essere controllate quando l'istruzione viene preparata (se sono stati associati tutti i parametri) o quando vengono eseguiti (se tutti i parametri non sono stati associati). Per garantire la massima interoperabilità, un'applicazione deve annullare l'associazione di tutti i parametri applicati a un'istruzione SQL precedente prima di preparare una nuova istruzione SQL nella stessa istruzione. In questo modo si evitano errori dovuti alle informazioni sui parametri precedenti applicate alla nuova istruzione.
Importante
Il commit di una transazione, chiamando in modo esplicito SQLEndTran o utilizzando la modalità autocommit, può causare l'eliminazione dei piani di accesso per tutte le istruzioni in una connessione. Per altre informazioni, vedere i tipi di informazioni SQL_CURSOR_COMMIT_BEHAVIOR e SQL_CURSOR_ROLLBACK_BEHAVIOR in SQLGetInfo ed effetto delle transazioni sui cursori e istruzioni preparate.
Esempio di codice
Vedere SQLBindParameter, SQLPutData e SQLSetPos.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Allocazione di un handle di istruzione | Funzione SQLAllocHandle |
| Associazione di un buffer a una colonna in un set di risultati | Funzione SQLBindCol |
| Associazione di un buffer a un parametro | Funzione SQLBindParameter |
| Annullamento dell'elaborazione delle istruzioni | Funzione SQLCancel |
| Esecuzione di un'operazione di commit o rollback | Funzione SQLEndTran |
| Esecuzione di un'istruzione SQL | Funzione SQLExecDirect |
| Esecuzione di un'istruzione SQL preparata | Funzione SQLExecute |
| Restituzione del numero di righe interessate da un'istruzione | Funzione SQLRowCount |
| Impostazione di un nome di cursore | Funzione SQLSetCursorName |