Funzione SQLMoreResults

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

Summary
SQLMoreResults determina se sono disponibili altri risultati in un'istruzione contenente istruzioni SELECT, UPDATE, INSERT o DELETE e, in tal caso, inizializza l'elaborazione per tali risultati.

Sintassi

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);  

Argomenti

StatementHandle
[Input] Handle di istruzione.

Restituisce

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE o SQL_PARAM_DATA_AVAILABLE.

Diagnostica

Quando SQLMoreResults 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 SQLMoreResults e spiega ognuno di essi 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 specificato diversamente.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. La funzione restituisce SQL_SUCCESS_WITH_INFO.
01S02 Il valore dell'opzione è stato modificato Il valore di un attributo di istruzione è stato modificato durante l'elaborazione del batch. 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.
40001 Errore di serializzazione È stato eseguito il rollback della transazione a causa di un deadlock delle risorse con un'altra transazione.
40003 Completamento istruzioni sconosciuto La connessione associata non è riuscita durante l'esecuzione di questa funzione e non è possibile determinare lo stato della transazione.
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. È stata chiamata la funzione SQLMoreResults e, prima del completamento dell'esecuzione, è stato chiamato SQLCancel o SQLCancelHandle su StatementHandle. La funzione SQLMoreResults è stata quindi chiamata nuovamente in StatementHandle.

È stata chiamata la funzione SQLMoreResults e, prima del completamento dell'esecuzione, è stato chiamato SQLCancel o SQLCancelHandle su StatementHandle da un thread diverso in un'applicazione multithread.
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 SQLMoreResults.

(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.
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.
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

Le istruzioni SELECT restituiscono set di risultati. Le istruzioni UPDATE, INSERT e DELETE restituiscono un conteggio delle righe interessate. Se una di queste istruzioni è in batch, inviata con matrici di parametri (numerate in ordine crescente di parametri, nell'ordine in cui sono visualizzate nel batch) o nelle procedure, possono restituire più set di risultati o conteggi di righe. Per informazioni sui batch di istruzioni e matrici di parametri, vedere Batch di istruzioni SQL e matrici di valori di parametro.

Dopo l'esecuzione del batch, l'applicazione viene posizionata sul primo set di risultati. L'applicazione può chiamare SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos e tutte le funzioni di metadati, nel primo set di risultati o in qualsiasi set di risultati successivo, come se fosse presente un solo set di risultati. Al termine dell'operazione con il primo set di risultati, l'applicazione chiama SQLMoreResults per passare al set di risultati successivo. Se è disponibile un altro set di risultati o un altro conteggio, SQLMoreResults restituisce SQL_SUCCESS e inizializza il set di risultati o il conteggio per un'elaborazione aggiuntiva. Se tra le istruzioni che generano set di risultati vengono visualizzate istruzioni che generano il conteggio delle righe, è possibile eseguire un'istruzione per eseguire un'istruzione successiva chiamando SQLMoreResults. Dopo aver chiamato SQLMoreResults per le istruzioni UPDATE, INSERT o DELETE, un'applicazione può chiamare SQLRowCount.

Se è presente un set di risultati corrente con righe senzatch, SQLMoreResults rimuove il set di risultati e rende disponibile il set di risultati o il conteggio successivo. Se tutti i risultati sono stati elaborati, SQLMoreResults restituisce SQL_NO_DATA. Per alcuni driver, i parametri di output e i valori restituiti non sono disponibili fino a quando non sono stati elaborati tutti i set di risultati e i conteggi delle righe. Per tali driver, i parametri di output e i valori restituiti diventano disponibili quando SQLMoreResults restituisce SQL_NO_DATA.

Tutte le associazioni stabilite per il set di risultati precedente rimangono comunque valide. Se le strutture delle colonne sono diverse per questo set di risultati, la chiamata di SQLFetch o SQLFetchScroll può comportare un errore o un troncamento. Per evitare questo problema, l'applicazione deve chiamare SQLBindCol per riassociare in modo esplicito in base alle esigenze (o farlo impostando i campi del descrittore). In alternativa, l'applicazione può chiamare SQLFreeStmt con un'opzione SQL_UNBIND per disassociare tutti i buffer di colonna.

I valori degli attributi dell'istruzione, ad esempio il tipo di cursore, la concorrenza del cursore, la dimensione del keyset o la lunghezza massima, possono cambiare man mano che l'applicazione si sposta nel batch tramite chiamate a SQLMoreResults. In questo caso, SQLMoreResults restituirà SQL_SUCCESS_WITH_INFO e SQLSTATE 01S02 (il valore dell'opzione è stato modificato).

Chiamando SQLCloseCursor o SQLFreeStmt con un'opzione SQL_CLOSE, vengono eliminati tutti i set di risultati e i conteggi delle righe disponibili in seguito all'esecuzione del batch. L'handle di istruzione torna allo stato allocato o preparato. Se si chiama SQLCancel per annullare una funzione in esecuzione in modo asincrono quando un batch è stato eseguito e l'handle di istruzione si trova nello stato eseguito, posizionato sul cursore o asincrono, tutti i set di risultati e i conteggi delle righe generati dal batch vengono eliminati se la chiamata di annullamento ha avuto esito positivo. L'istruzione torna quindi allo stato preparato o allocato.

Se un batch di istruzioni o una routine combina altre istruzioni SQL con le istruzioni SELECT, UPDATE, INSERT e DELETE, queste altre istruzioni non influiscono su SQLMoreResults.

Per altre informazioni, vedere Più risultati.

Se un'istruzione di aggiornamento, inserimento o eliminazione ricercata in un batch di istruzioni non influisce sulle righe nell'origine dati, SQLMoreResults restituisce SQL_SUCCESS. Ciò è diverso dal caso di un'istruzione di aggiornamento, inserimento o eliminazione eseguita tramite SQLExecDirect, SQLExecute o SQLParamData, che restituisce SQL_NO_DATA se non influisce su alcuna riga nell'origine dati. Se un'applicazione chiama SQLRowCount per recuperare il conteggio delle righe dopo che una chiamata a SQLMoreResults non ha interessato alcuna riga, SQLRowCount restituirà SQL_NO_DATA.

Per altre informazioni sulla sequenziazione valida delle funzioni di elaborazione dei risultati, vedere Appendice B: Tabelle di transizione dello stato ODBC.

Per altre informazioni sui parametri SQL_PARAM_DATA_AVAILABLE e di output trasmessi, vedere Recupero di parametri di output tramite SQLGetData.

Disponibilità dei conteggi delle righe

Quando un batch contiene più istruzioni consecutive che generano il conteggio delle righe, è possibile che il rollup di questi conteggi di righe venga eseguito in un solo conteggio di righe. Ad esempio, se un batch ha cinque istruzioni insert, determinate origini dati sono in grado di restituire cinque singoli conteggi di righe. Alcune altre origini dati restituiscono un solo conteggio di righe che rappresenta la somma dei cinque conteggi delle singole righe.

Quando un batch contiene una combinazione di istruzioni di generazione di set di risultati e di generazione del numero di righe, i conteggi delle righe possono essere o meno disponibili. Il comportamento del driver rispetto alla disponibilità dei conteggi delle righe viene enumerato nel tipo di informazioni SQL_BATCH_ROW_COUNT disponibile tramite una chiamata a SQLGetInfo. Si supponga, ad esempio, che il batch contenga un elemento SELECT, seguito da due insert e un altro SELECT. Sono quindi possibili i casi seguenti:

  • I conteggi delle righe corrispondenti alle due istruzioni INSERT non sono disponibili. La prima chiamata a SQLMoreResults posiziona l'utente sul set di risultati della seconda istruzione SELECT.

  • I conteggi delle righe corrispondenti alle due istruzioni INSERT sono disponibili singolarmente. Una chiamata a SQLGetInfo non restituisce il bit SQL_BRC_ROLLED_UP per il SQL_BATCH_ROW_COUNT di informazioni. La prima chiamata a SQLMoreResults posiziona l'utente sul conteggio delle righe del primo INSERT e la seconda chiamata posiziona l'utente sul conteggio delle righe della seconda istruzione INSERT. La terza chiamata a SQLMoreResults posiziona l'utente sul set di risultati della seconda istruzione SELECT.

  • Il rollup dei conteggi delle righe corrispondenti ai due INSERT viene eseguito in un unico conteggio di righe disponibile. Una chiamata a SQLGetInfo restituisce il bit SQL_BRC_ROLLED_UP bit per il SQL_BATCH_ROW_COUNT di informazioni. La prima chiamata a SQLMoreResults posiziona l'utente sul conteggio delle righe di cui è stato eseguito il rollup e la seconda chiamata a SQLMoreResults posiziona l'utente sul set di risultati della seconda istruzione SELECT.

Alcuni driver rendono disponibili i conteggi delle righe solo per i batch espliciti e non per le stored procedure.

Per informazioni su Vedere
Annullamento dell'elaborazione dell'istruzione Funzione SQLCancel
Recupero di un blocco di dati o scorrimento di un set di risultati Funzione SQLFetchScroll
Recupero di una singola riga o di un blocco di dati in una direzione forward-only Funzione SQLFetch
Recupero di parte o di tutta una colonna di dati Funzione SQLGetData

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC
Recupero di parametri di output tramite SQLGetData