Funzione SQLMoreResults

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

Riepilogo
SQLMoreResults determina se sono disponibili più 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.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE, OR 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 di 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 SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

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 viene inviata in batch, inviata con matrici di parametri (numerati in ordine crescente dei parametri, nell'ordine in cui vengono visualizzati 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 dei parametri.

Dopo l'esecuzione del batch, l'applicazione viene posizionata nel primo set di risultati. L'applicazione può chiamare SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos e tutte le funzioni di metadati, nel primo o in qualsiasi set di risultati successivo, proprio come se fosse presente un singolo set di risultati. Al termine del primo set di risultati, l'applicazione chiama SQLMoreResults per passare al set di risultati successivo. Se è disponibile un altro set di risultati o conteggio, SQLMoreResults restituisce SQL_SUCCESS e inizializza il set di risultati o il conteggio per un'elaborazione aggiuntiva. Se tra le istruzioni di generazione del set di risultati vengono visualizzate istruzioni di generazione di righe, è possibile passare tramite una chiamata a SQLMoreResults. Dopo aver chiamato SQLMoreResults per istruzioni UPDATE, INSERT o DELETE, un'applicazione può chiamare SQLRowCount.

Se è presente un set di risultati corrente con righe non recuperate, SQLMoreResults elimina 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 vengono 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.

Le associazioni stabilite per il set di risultati precedente rimangono ancora valide. Se le strutture di colonna sono diverse per questo set di risultati, la chiamata a 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 impostando i campi del descrittore). In alternativa, l'applicazione può chiamare SQLFreeStmt con un'opzione di SQL_UNBIND per annullare l'associazione di tutti i buffer di colonna.

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

La chiamata a SQLCloseCursor o SQLFreeStmt con un'opzione di SQL_CLOSE elimina tutti i set di risultati e i conteggi di righe disponibili in seguito all'esecuzione del batch. L'handle di istruzione restituisce lo stato allocato o preparato. Chiamando SQLCancel per annullare una funzione in esecuzione asincrona quando è stato eseguito un batch e l'handle di istruzione si trova nello stato eseguito, posizionato nel cursore o in uno stato asincrono, vengono restituiti tutti i set di risultati e i conteggi delle righe generati dal batch ignorato se la chiamata di annullamento ha avuto esito positivo. L'istruzione restituisce quindi lo stato preparato o allocato.

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

Per altre informazioni, vedere Più risultati.

Se un'istruzione searched update, insert o delete in un batch di istruzioni non influisce sulle righe nell'origine dati, SQLMoreResults restituisce SQL_SUCCESS. Questo comportamento è 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 sulle righe nell'origine dati. Se un'applicazione chiama SQLRowCount per recuperare il conteggio delle righe dopo una chiamata a SQLMoreResults non ha alcun effetto sulle righe, 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 di output SQL_PARAM_DATA_AVAILABLE e trasmessi, vedere Recupero di parametri di output tramite SQLGetData.

Disponibilità dei conteggi delle righe

Quando un batch contiene più istruzioni consecutive di generazione del conteggio delle righe, è possibile che questi conteggi di righe vengano distribuiti in un solo conteggio di righe. Ad esempio, se un batch ha cinque istruzioni insert, alcune 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 conteggio righe, i conteggi delle righe possono essere disponibili o meno. 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 s INSERTe un altro SELECT. Sono quindi possibili i casi seguenti:

• I conteggi delle righe corrispondenti alle due istruzioni INSERT non sono disponibili affatto. La prima chiamata a SQLMoreResults verrà posizionata nel 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 di SQL_BRC_ROLLED_UP per il tipo di informazioni SQL_BATCH_ROW_COUNT. La prima chiamata a SQLMoreResults posizionerà il conteggio delle righe del primo INSERT e la seconda posizionerà il conteggio delle righe del secondo INSERT. La terza chiamata a SQLMoreResults posiziona l'utente nel set di risultati della seconda istruzione SELECT .

• I conteggi delle righe corrispondenti ai due INSERT vengono distribuiti in un unico numero di righe disponibile. (Una chiamata a SQLGetInfo restituisce il bit di SQL_BRC_ROLLED_UP per il tipo di informazioni SQL_BATCH_ROW_COUNT. La prima chiamata a SQLMoreResults posizionerà il conteggio delle righe di rollup e la seconda chiamata a SQLMoreResults posizionerà il set di risultati del secondo select.

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

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC
Recupero di parametri di output tramite SQLGetData