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.

Resi

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 handleTypedi 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 valoredel criterio LIKEnella 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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC