SQLEndTran Function
Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92
Riepilogo
SQLEndTran richiede un'operazione di commit o rollback per tutte le operazioni attive su tutte le istruzioni associate a una connessione. SQLEndTran può anche richiedere l'esecuzione di un'operazione di commit o rollback per tutte le connessioni associate a un ambiente.
Nota
Per altre informazioni su ciò che Gestione driver esegue il mapping di questa funzione a quando un ODBC 3.L'applicazione x funziona con odbc 2.x driver, vedere Mapping di funzioni di sostituzione per la compatibilità con le versioni precedenti delle applicazioni.
Sintassi
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Argomenti
HandleType
[Input] Identificatore del tipo di handle. Contiene SQL_HANDLE_ENV (se Handle è un handle di ambiente) o SQL_HANDLE_DBC (se Handle è un handle di connessione).
Handle
[Input] Handle, del tipo indicato da HandleType, che indica l'ambito della transazione. Per altre informazioni, vedere "Commenti".
CompletionType
[Input] Uno dei due valori seguenti:
SQL_COMMIT SQL_ROLLBACK
Valori restituiti
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.
Diagnostica
Quando SQLEndTran restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handle e handle appropriati. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLEndTran 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. |
| 08003 | Connessione non aperta | (DM) HandleType è stato SQL_HANDLE_DBC e handle non era in uno stato connesso. |
| 08007 | Errore di connessione durante la transazione | HandleType è stato SQL_HANDLE_DBC e la connessione associata all'handle non è riuscita durante l'esecuzione della funzione e non può essere determinato se il COMMIT o ROLLBACK richiesto si è verificato prima dell'errore. |
| 25S01 | Stato della transazione sconosciuto | Una o più connessioni in Handle non sono riuscite a completare la transazione con il risultato specificato e il risultato è sconosciuto. |
| 25S02 | La transazione è ancora attiva | Il driver non è riuscito a garantire che tutto il lavoro nella transazione globale possa essere completato in modo atomico e che la transazione sia ancora attiva. |
| 25S03 | Viene eseguito il rollback della transazione | Il driver non è riuscito a garantire che tutto il lavoro nella transazione globale possa essere completato in modo atomico e tutto il lavoro nella transazione attiva in Handle è stato eseguito il rollback. |
| 40001 | Errore di serializzazione | È stato eseguito il rollback della transazione a causa di un deadlock della risorsa con un'altra transazione. |
| 40002 | Violazione del vincolo di integrità | CompletionType è stato SQL_COMMIT e l'impegno delle modifiche ha causato la violazione del vincolo di integrità. Di conseguenza, è stato eseguito il rollback della transazione. |
| 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 *szMessageText 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 ConnectionHandle. La funzione è stata chiamata e prima di terminare l'esecuzione della funzione SQLCancelHandle è stata chiamata in ConnectionHandle. La funzione è stata quindi chiamata di nuovo in ConnectionHandle. La funzione è stata chiamata e prima di terminare l'esecuzione di SQLCancelHandle è stata chiamata su ConnectionHandle da un thread diverso in un'applicazione multithread. |
| HY010 | Errore della sequenza di funzioni | (DM) È stata chiamata una funzione in esecuzione asincrona per un handle di istruzione associato a ConnectionHandle ed è ancora in esecuzione quando è stato chiamato SQLEndTran . (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per ConnectionHandle ed era ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per un handle di istruzione associato a ConnectionHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution. (DM) È stata chiamata una funzione in esecuzione asincrona (non questa) per Handle con HandleType impostata su SQL_HANDLE_DBC ed era ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per uno degli handle di istruzione associati a Handle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. |
| HY012 | Codice dell'operazione di transazione non valido | (DM) Il valore specificato per l'argomento CompletionType non è stato né SQL_COMMIT né SQL_ROLLBACK. |
| 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. |
| HY092 | Identificatore di attributo/opzione non valido | (DM) Il valore specificato per l'argomento HandleType non è stato né SQL_HANDLE_ENV né SQL_HANDLE_DBC. |
| HY115 | SQLEndTran non è consentito per un ambiente che contiene una connessione con l'esecuzione asincrona di funzioni abilitata | (DM) HandleType non può essere impostato su SQL_HANDLE_ENV se l'esecuzione asincrona delle funzioni di connessione è abilitata per una connessione nell'ambiente. |
| 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 la sezione Commenti di questo argomento. |
| HYC00 | Funzionalità facoltativa non implementata | Il driver o l'origine dati non supporta l'operazione ROLLBACK . |
| 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 ConnectionHandle 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
Per odbc 3.x driver, se HandleType è SQL_HANDLE_ENV e Handle è un handle di ambiente valido, Gestione driver chiamerà SQLEndTran in ogni driver associato all'ambiente. L'argomento Handle per la chiamata a un driver sarà l'handle dell'ambiente del driver. Per odbc 2.x driver, se HandleType è SQL_HANDLE_ENV e Handle è un handle di ambiente valido e sono presenti più connessioni in uno stato connesso in tale ambiente, Gestione driver chiamerà SQLTransact nel driver una volta per ogni connessione in uno stato connesso in tale ambiente. L'argomento Handle in ogni chiamata sarà l'handle della connessione. In entrambi i casi, il driver tenterà di eseguire il commit o il rollback delle transazioni, a seconda del valore di CompletionType, su tutte le connessioni in uno stato connesso in tale ambiente. Le connessioni non attive non influiscono sulla transazione.
Nota
SQLEndTran non può essere usato per eseguire il commit o il rollback delle transazioni in un ambiente condiviso. SQLSTATE HY092 (identificatore di attributo/opzione non valido) verrà restituito se SQLEndTran viene chiamato con Handle impostato sull'handle di un ambiente condiviso o sull'handle di una connessione in un ambiente condiviso.
Gestione driver restituirà SQL_SUCCESS solo se riceve SQL_SUCCESS per ogni connessione. Se Gestione driver riceve SQL_ERROR su una o più connessioni, restituisce SQL_ERROR all'applicazione e le informazioni di diagnostica vengono inserite nella struttura dei dati di diagnostica dell'ambiente. Per determinare la connessione o le connessioni non riuscite durante l'operazione di commit o rollback, l'applicazione può chiamare SQLGetDiagRec per ogni connessione.
Nota
Gestione driver non simula una transazione globale in tutte le connessioni e pertanto non usa protocolli di commit in due fasi.
Se CompletionType è SQL_COMMIT, SQLEndTran invia una richiesta di commit per tutte le operazioni attive su qualsiasi istruzione associata a una connessione interessata. Se CompletionType è SQL_ROLLBACK, SQLEndTran invia una richiesta di rollback per tutte le operazioni attive su qualsiasi istruzione associata a una connessione interessata. Se non sono attive transazioni, SQLEndTran restituisce SQL_SUCCESS senza alcun effetto sulle origini dati. Per altre informazioni, vedere Commit e rollback delle transazioni.
Se il driver è in modalità di commit manuale (chiamando SQLSetConnectAttr con l'attributo SQL_ATTR_AUTOCOMMIT impostato su SQL_AUTOCOMMIT_OFF), una nuova transazione viene avviata in modo implicito quando viene eseguita un'istruzione SQL che può essere contenuta all'interno di una transazione sull'origine dati corrente. Per altre informazioni, vedere Modalità commit.
Per determinare il modo in cui le operazioni delle transazioni influiscono sui cursori, un'applicazione chiama SQLGetInfo con le opzioni SQL_CURSOR_ROLLBACK_BEHAVIOR e SQL_CURSOR_COMMIT_BEHAVIOR. Per altre informazioni, vedere i paragrafi seguenti e vedere anche Effetto delle transazioni sui cursori e istruzioni preparate.
Se il valore SQL_CURSOR_ROLLBACK_BEHAVIOR o SQL_CURSOR_COMMIT_BEHAVIOR è uguale a SQL_CB_DELETE, SQLEndTran chiude ed elimina tutti i cursori aperti in tutte le istruzioni associate alla connessione e rimuove tutti i risultati in sospeso. SQLEndTran lascia qualsiasi istruzione presente in uno stato allocato (non preparato). L'applicazione può riutilizzarle per le richieste SQL successive o può chiamare SQLFreeStmt o SQLFreeHandle con handleType di SQL_HANDLE_STMT per deallocarle.
Se il valore SQL_CURSOR_ROLLBACK_BEHAVIOR o SQL_CURSOR_COMMIT_BEHAVIOR è uguale a SQL_CB_CLOSE, SQLEndTran chiude tutti i cursori aperti in tutte le istruzioni associate alla connessione. SQLEndTran lascia qualsiasi istruzione presente in uno stato preparato. L'applicazione può chiamare SQLExecute per un'istruzione associata alla connessione senza prima chiamare SQLPrepare.
Se il valore SQL_CURSOR_ROLLBACK_BEHAVIOR o SQL_CURSOR_COMMIT_BEHAVIOR è uguale a SQL_CB_PRESERVE, SQLEndTran non influisce sui cursori aperti associati alla connessione. I cursori rimangono nella riga a cui puntavano prima della chiamata a SQLEndTran.
Per i driver e le origini dati che supportano le transazioni, chiamare SQLEndTran con SQL_COMMIT o SQL_ROLLBACK quando nessuna transazione è attiva restituisce SQL_SUCCESS (a indicare che non è necessario eseguire il commit o il rollback) e non ha alcun effetto sull'origine dati.
Quando un driver è in modalità autocommit, Gestione driver non chiama SQLEndTran nel driver. SQLEndTran restituisce sempre SQL_SUCCESS indipendentemente dal fatto che venga chiamato con completionType di SQL_COMMIT o SQL_ROLLBACK.
I driver o le origini dati che non supportano le transazioni (l'opzione SQLGetInfo SQL_TXN_CAPABLE è SQL_TC_NONE) sono sempre in modalità autocommit e pertanto restituiscono sempre SQL_SUCCESS per SQLEndTran indipendentemente dal fatto che vengano chiamati con un valore CompletionType di SQL_COMMIT o SQL_ROLLBACK. Tali driver e origini dati non eseguono effettivamente il rollback delle transazioni quando richiesto di farlo.
Stato sospeso
In Gestori driver rilasciati prima di Windows 7, una transazione era attiva se SQLEndTran ha restituito SQL_ERROR dal driver. Tuttavia, è stato possibile che la transazione sia stata eseguita correttamente nel server, ma il driver sul client non è stato informato (ad esempio, perché si è verificato un errore di rete). In questo modo la connessione viene lasciata in uno stato non valido. A partire da Windows 7, quando SQLEndTran restituisce SQL_ERROR, la connessione potrebbe trovarsi in uno stato sospeso. In uno stato sospeso, è possibile chiamare funzioni di sola lettura. Infine, l'applicazione deve chiamare SQLDisconnect in una connessione sospesa per rilasciare le risorse.
Se tutte le condizioni seguenti sono vere, la connessione verrà inserita in uno stato sospeso:
Il driver restituisce SQL_ERROR da SQLEndTran.
Il driver è ODBC versione 3.8 o successiva.
La versione dell'applicazione è 3.8 o successiva; o l'applicazione ODBC 2.x o 3.x ricompilata annulla correttamente la funzione SQLEndTran tramite SQLCancelHandle.
Il driver non ha restituito uno dei messaggi seguenti, che confermano che la transazione non è stata completata:
25S03: Viene eseguito il rollback della transazione
40001: Errore di serializzazione
40002: Vincolo di integrità
HYC00: funzionalità facoltativa non implementata
Se SQLEndTran è stato chiamato su un handle di ambiente e una delle relative connessioni ha soddisfatto le condizioni precedenti, tutte le connessioni che si connettono allo stesso driver verranno inserite nello stato sospeso.
Dopo che un'applicazione chiama SQLDisconnect in una connessione sospesa, la connessione può essere usata per riconnettersi a un'altra origine dati o alla stessa origine dati.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Annullamento di una funzione in esecuzione in modo asincrono in un handle di connessione. | Funzione SQLCancelHandle |
| Restituzione di informazioni su un driver o un'origine dati | Funzione SQLGetInfo |
| Liberare un handle | Funzione SQLFreeHandle |
| Liberare un handle di istruzione | Funzione SQLFreeStmt |
Vedi anche
Riferimento API ODBC
File di intestazione ODBC
Esecuzione asincrona (metodo di polling)