Pagina relativa alla funzione SQLPrepare

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92

Summary
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] SQL stringa di testo.

TextLength
[Input] Lunghezza di *StatementText in caratteri.

Restituisce

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 SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLPrepare e ne illustra ognuno nel contesto di questa funzione. la notazione "(DM)" precede le descrizioni di SQLSTATE restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, se non diversamente specificato.

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 di condizioni di lavoro di implementazione, pertanto un valore simile è stato sostituito temporaneamente. È possibile chiamare SQLGetStmtAttr per determinare qual è il valore sostituito temporaneamente. Il valore sostitutivo è valido per StatementHandle finché il cursore non viene chiuso. 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 Il 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 Grado di tabella derivata non corrispondente all'elenco di colonne *StatementText contiene un'istruzione CREATE VIEW e il numero di nomi specificato non corrisponde al grado della tabella derivata definita dalla specifica della query.
22018 Valore di carattere non valido per la specifica del cast *StatementText contiene un SQL che contiene un valore letterale o un parametro e il valore non è compatibile con il tipo di dati della colonna della 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 che segue ESCAPE non è uguale a 1.
22025 Sequenza di escape non valida L'argomento StatementText contiene "Like pattern value ESCAPE escape character" nella clausola WHERE e il carattere che segue il carattere di escape nel valore del criterio non è "%" né "_".
24000 Stato del cursore non valido (DM) È stato aperto un cursore in StatementHandle ed è stato chiamato SQLFetch o SQLFetchScroll.

È stato aperto un cursore in StatementHandle, ma non è stato chiamato SQLFetch o SQLFetchScroll.
34000 Nome di cursore non valido *StatementText conteneva un'istruzione DELETE o UPDATE posizionata e il cursore a cui fa riferimento l'istruzione preparata non era aperto.
3D000 Nome di catalogo non valido Il nome del catalogo specificato in StatementText non è valido.
3F000 Nome di schema non valido Il nome dello schema specificato in StatementText non è valido.
42000 Errore di sintassi o violazione di accesso *StatementText contiene un'SQL istruzione non preparabile o contenente un errore di sintassi.

*StatementText contiene un'istruzione per la quale l'utente non dispone dei privilegi necessari.
42S01 La tabella o la vista di base esiste già *StatementText contiene un'CREATE TABLE o CREATE VIEW e il nome di tabella o di 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 esiste.

*StatementText contiene un'istruzione ALTER TABLE e il nome di tabella specificato non esiste.

*StatementText contiene un'istruzione CREATE VIEW e non esiste un nome di tabella o di vista definito dalla specifica della query.

*StatementText contiene un'istruzione CREATE INDEX e il nome di 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 di vista specificato non esiste.

*StatementText contiene un'istruzione DELETE, INSERT o UPDATE e il nome di tabella specificato non esiste.

*StatementText contiene CREATE TABLE istruzione e una tabella specificata in un vincolo (che fa riferimento a una tabella diversa da quella creata) non esiste.
42S11 L'indice esiste già *StatementText contiene un'istruzione CREATE INDEX e il nome di indice specificato esiste già.
42S12 Indice non trovato *StatementText contiene un DROP INDEX istruzione e il nome di indice specificato non esiste.
42S21 La colonna esiste già *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 contiene un'istruzione GRANT o REVOKE e il nome di colonna specificato non esiste.

*StatementText contiene un'istruzione SELECT, DELETE, INSERT o UPDATE e il nome di colonna specificato non esiste.

*StatementText contiene CREATE TABLE istruzione e una colonna specificata in un vincolo (che fa riferimento a una tabella diversa da quella creata) non esiste.
HY000 Errore generale: Si è verificato un errore per il quale non esiste un SQLSTATE specifico e per il quale non è stato definito 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 la memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY008 Operation canceled L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle e quindi la funzione è stata chiamata nuovamente su StatementHandle.

La funzione è stata chiamata e prima del completamento dell'esecuzione è stato chiamato SQLCancel o SQLCancelHandle su StatementHandle da un thread diverso in un'applicazione multithreading.
HY009 Uso non valido del puntatore Null StatementText è un puntatore Null.
HY010 Errore della sequenza di funzione (DM) È stata chiamata una funzione in esecuzione in modo asincrono 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 ha restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi.

(DM) Una funzione in esecuzione in modo asincrono (non questa) è stata chiamata per StatementHandle ed era ancora in esecuzione quando è stata chiamata questa funzione.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos sono stati chiamati per StatementHandle e sono stati restituiti 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 Non è stato possibile 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 di stringa o buffer non valida (DM) L'argomento TextLength è minore o uguale a 0, ma non è uguale a SQL_NTS.
HY117 La connessione è stata sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo le funzioni di disconnessione e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYC00 Funzionalità facoltativa non implementata L'impostazione di concorrenza non è valida per il tipo di cursore definito.

L SQL_ATTR_USE_BOOKMARKS'attributo dell'istruzione è stato impostato su SQL_UB_VARIABLE e l'attributo dell'istruzione SQL_ATTR_CURSOR_TYPE è stato impostato su un tipo di cursore per il quale il driver non supporta i segnalibri.
HYT00 Timeout Il periodo di timeout è scaduto prima che l'origine dati ha restituito il set di risultati. Il periodo di timeout viene impostato tramite SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Timeout della connessione scaduto Il periodo di timeout della connessione è scaduto prima che l'origine dati risponda 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 SQL'istruzione 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 SQL istruzione . Per includere un marcatore di parametro, l'applicazione incorpora un punto interrogativo (?) nella stringa SQL nella posizione appropriata. Per informazioni sui parametri, vedere Parametri dell'istruzione.

Nota

Se un'applicazione usa SQLPrepare per preparare e SQLExecute per inviare un'istruzione COMMIT o ROLLBACK, non sarà interoperativizzabile 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 utilizzare il formato SQL utilizzato dall'origine dati e quindi inviarla all'origine dati per la preparazione. In particolare, il driver modifica le sequenze di escape usate per definire SQL sintassi per determinate funzionalità. Per una descrizione della grammatica SQL istruzione, vedere Sequenze di escape in ODBC e Appendice C: SQL grammatica. 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 rieseguita 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 a una delle funzioni di catalogo (SQLColumns, SQLTables e così via). Dopo che l'applicazione ha preparato un'istruzione, può richiedere informazioni sul formato del set di risultati. Per alcune implementazioni, la chiamata di SQLDescribeCol o SQLDescribeParam dopo SQLPrepare potrebbe non essere efficiente quanto 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) possono essere controllate quando l'istruzione viene preparata (se sono stati associati tutti i parametri) o quando viene eseguita (se tutti i parametri non sono stati associati). Per garantire la massima interoperabilità, un'applicazione deve disassociare 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 a informazioni sui parametri non aggiornate applicate alla nuova istruzione.

Importante

Il commit di una transazione, chiamando in modo esplicito SQLEndTran o usando la modalità autocommit, può causare l'eliminazione dei piani di accesso per tutte le istruzioni in una connessione da parte dell'origine dati. Per altre informazioni, vedere i SQL_CURSOR_COMMIT_BEHAVIOR e SQL_CURSOR_ROLLBACK_BEHAVIOR in SQLGetInfo e Effetto delle transazioni sui cursori e sulle istruzioni preparate.

Esempio di codice

Vedere SQLBindParameter, SQLPutDatae SQLSetPos.

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 Pagina relativa alla funzione SQLBindParameter
Annullamento dell'elaborazione dell'istruzione Funzione SQLCancel
Esecuzione di un'operazione di commit o rollback SQLEndTran Function
Esecuzione di un'istruzione SQL'istruzione Funzione SQLExecDirect
Esecuzione di un'istruzione SQL preparata Funzione SQLExecute
Restituzione del numero di righe interessate da un'istruzione SQLRowCount Function
Impostazione del nome di un cursore Funzione SQLSetCursorName

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC