Funzione SQLFetch
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92
Riepilogo
SQLFetch recupera il set di righe successivo di dati dal set di risultati e restituisce i dati per tutte le colonne associate.
Sintassi
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
Argomenti
StatementHandle
[Input] Handle di istruzione.
Valori restituiti
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLFetch restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando la funzione SQLGetDiagRec con handleType di SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLFetch 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. Se si verifica un errore in una singola colonna, è possibile chiamare SQLGetDiagField con un DiagIdentifier di SQL_DIAG_COLUMN_NUMBER per determinare la colonna in cui si è verificato l'errore e SQLGetDiagField può essere chiamato con un DiagIdentifier di SQL_DIAG_ROW_NUMBER per determinare la riga contenente tale colonna.
Per tutti gli SQLSTATEs che possono restituire SQL_SUCCESS_WITH_INFO o SQL_ERROR (ad eccezione di 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO viene restituito se si verifica un errore in una o più righe, ma non tutte, righe di un'operazione multirow e SQL_ERROR viene restituito se si verifica un errore in un'operazione a riga singola.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| 01000 | Avviso generale | Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01004 | Dati stringa, troncati a destra | I dati stringa o binari restituiti per una colonna hanno comportato il troncamento di dati binari non null o non NULL. Se si tratta di un valore stringa, è stato troncato a destra. |
| 01S01 | Errore nella riga | Errore durante il recupero di una o più righe. Se questo SQLSTATE viene restituito quando un'applicazione ODBC 3*.x* utilizza un driver ODBC 2*.x*, può essere ignorata. |
| 01S07 | Troncamento frazionario | I dati restituiti per una colonna sono stati troncati. Per i tipi di dati numerici, la parte frazionaria del numero è stata troncata. Per i tipi di dati time, timestamp e interval che contengono un componente time, la parte frazionaria dell'ora è stata troncata. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 07006 | Violazione dell'attributo del tipo di dati con restrizioni | Impossibile convertire il valore di dati di una colonna nel set di risultati nel tipo di dati specificato da TargetType in SQLBindCol. La colonna 0 è stata associata a un tipo di dati di SQL_C_BOOKMARK e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_VARIABLE. La colonna 0 è stata associata a un tipo di dati di SQL_C_VARBOOKMARK e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS non è stato impostato su SQL_UB_VARIABLE. |
| 07009 | Indice descrittore non valido | Il driver era un driver ODBC 2*.x* che non supporta SQLExtendedFetch e un numero di colonna specificato nell'associazione per una colonna era 0. La colonna 0 è stata associata e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_OFF. |
| 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. |
| 22001 | Dati stringa, troncati a destra | Un segnalibro a lunghezza variabile restituito per una colonna è stato troncato. |
| 22002 | Variabile indicatore obbligatoria ma non fornita | I dati NULL sono stati recuperati in una colonna il cui StrLen_or_IndPtr impostato da SQLBindCol (o SQL_DESC_INDICATOR_PTR impostato da SQLSetDescField o SQLSetDescRec) era un puntatore Null. |
| 22003 | Valore numerico non compreso nell'intervallo | La restituzione del valore numerico come numerico o stringa per una o più colonne associate avrebbe causato il troncamento dell'intera parte del numero , anziché frazionaria. Per altre informazioni, vedere Conversione di dati da SQL a tipi di dati C nell'Appendice D: Tipi di dati. |
| 22007 | Formato datetime non valido | Una colonna di caratteri nel set di risultati è stata associata a una struttura data, ora o timestamp C e un valore nella colonna era, rispettivamente, una data, un'ora o un timestamp non valido. |
| 22012 | Divisione per zero | È stato restituito un valore di un'espressione aritmetica, che ha determinato la divisione per zero. |
| 22015 | Overflow del campo intervallo | L'assegnazione da un tipo SQL numerico o intervallo esatto a un tipo C intervallo ha causato una perdita di cifre significative nel campo iniziale. Quando si recuperano dati a un tipo C di intervallo, non è presente alcuna rappresentazione del valore del tipo SQL nel tipo C intervallo. |
| 22018 | Valore carattere non valido per la specifica del cast | Una colonna di caratteri nel set di risultati è stata associata a un buffer C di caratteri e la colonna contiene un carattere per il quale non è presente alcuna rappresentazione nel set di caratteri del buffer. Il tipo C era un tipo numerico esatto o approssimativo, datetime o un tipo di dati interval; il tipo SQL della colonna era un tipo di dati carattere; e il valore nella colonna non era un valore letterale valido del tipo C associato. |
| 24000 | Stato del cursore non valido | StatementHandle era in uno stato eseguito, ma nessun set di risultati era associato a StatementHandle. |
| 40001 | Errore di serializzazione | La transazione in cui è stato eseguito il recupero è stata terminata per impedire il deadlock. |
| 40003 | Completamento istruzione 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 è 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 SQLFetch è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata su StatementHandle. La funzione SQLFetch è stata quindi chiamata nuovamente in StatementHandle. In alternativa, è stata chiamata la funzione SQLFetch e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread. |
| 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 SQLFetch . (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) StatementHandle specificato non era in uno stato eseguito. La funzione è stata chiamata senza prima chiamare SQLExecDirect, SQLExecute o una funzione del catalogo. (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. (DM) SQLFetch è stato chiamato per StatementHandle dopo la chiamata a SQLExtendedFetch e prima della chiamata di SQLFreeStmt con l'opzione SQL_CLOSE. |
| 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 | L'attributo dell'istruzione SQL_ATTR_USE_BOOKMARK è stato impostato su SQL_UB_VARIABLE e la colonna 0 è stata associata a un buffer la cui lunghezza non è uguale alla lunghezza massima per il segnalibro per questo set di risultati. Questa lunghezza è disponibile nel campo SQL_DESC_OCTET_LENGTH di IRD e può essere ottenuta chiamando SQLDescribeCol, SQLColAttribute o SQLGetDescField. |
| HY107 | Valore di riga non compreso nell'intervallo | Il valore specificato con l'attributo di istruzione SQL_ATTR_CURSOR_TYPE è stato SQL_CURSOR_KEYSET_DRIVEN, ma il valore specificato con l'attributo di istruzione SQL_ATTR_KEYSET_SIZE è maggiore di 0 e minore del valore specificato con l'attributo di istruzione SQL_ATTR_ROW_ARRAY_SIZE. |
| 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 | Il driver o l'origine dati non supporta la conversione specificata dalla combinazione di TargetType in SQLBindCol e il tipo di dati SQL della colonna corrispondente. |
| HYT00 | Timeout scaduto | Periodo di timeout della query scaduto prima che l'origine dati restituisca il set di risultati richiesto. 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
SQLFetch restituisce il set di righe successivo nel set di risultati. Può essere chiamato solo quando esiste un set di risultati, ovvero dopo una chiamata che crea un set di risultati e prima che il cursore su tale set di risultati venga chiuso. Se sono associate colonne, restituisce i dati in tali colonne. Se l'applicazione ha specificato un puntatore a una matrice di stato di riga o a un buffer in cui restituire il numero di righe recuperate, SQLFetch restituisce anche queste informazioni. Le chiamate a SQLFetch possono essere combinate con chiamate a SQLFetchScroll , ma non possono essere combinate con le chiamate a SQLExtendedFetch. Per altre informazioni, vedere Recupero di una riga di dati.
Se un'applicazione ODBC 3*.x* funziona con un driver ODBC 2*.x*, Gestione driver esegue il mapping delle chiamate SQLFetch a SQLExtendedFetch per un driver ODBC 2*.x* che supporta SQLExtendedFetch. Se il driver ODBC 2*.x* non supporta SQLExtendedFetch, Gestione driver esegue il mapping delle chiamate SQLFetch a SQLFetch nel driver ODBC 2*.x*, che può recuperare solo una singola riga.
Per altre informazioni, vedere Cursori rettangolari, cursori scorrevoli e compatibilità con le versioni precedenti nell'Appendice G: Linee guida del driver per la compatibilità con le versioni precedenti.
Posizionamento del cursore
Quando viene creato il set di risultati, il cursore viene posizionato prima dell'inizio del set di risultati. SQLFetch recupera il set di righe successivo. Equivale a chiamare SQLFetchScroll con FetchOrientation impostato su SQL_FETCH_NEXT. Per altre informazioni sui cursori, vedere Cursori e cursori a blocchi.
L'attributo dell'istruzione SQL_ATTR_ROW_ARRAY_SIZE specifica il numero di righe nel set di righe. Se il set di righe recuperato da SQLFetch si sovrappone alla fine del set di risultati, SQLFetch restituisce un set di righe parziale. Ovvero, se S + R - 1 è maggiore di L, dove S è la riga iniziale del set di righe recuperato, R è la dimensione del set di righe e L è l'ultima riga nel set di risultati, quindi solo la prima L - S + 1 righe del set di righe sono valide. Le righe rimanenti sono vuote e hanno uno stato di SQL_ROW_NOROW.
Dopo la restituzione di SQLFetch , la riga corrente è la prima riga del set di righe.
Le regole elencate nella tabella seguente descrivono il posizionamento del cursore dopo una chiamata a SQLFetch, in base alle condizioni elencate nella seconda tabella di questa sezione.
| Condizione | Prima riga del nuovo set di righe |
|---|---|
| Prima di iniziare | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | Dopo la fine |
| Dopo la fine | Dopo la fine |
[1] Se le dimensioni del set di righe vengono modificate tra i recuperi, si tratta della dimensione del set di righe usata con il recupero precedente.
[2] Se le dimensioni del set di righe vengono modificate tra i recuperi, si tratta della dimensione del set di righe usata con il nuovo recupero.
| Notazione | Significato |
|---|---|
| Prima di iniziare | Il cursore del blocco viene posizionato prima dell'inizio del set di risultati. Se la prima riga del nuovo set di righe è prima dell'inizio del set di risultati, SQLFetch restituisce SQL_NO_DATA. |
| Dopo la fine | Il cursore del blocco viene posizionato dopo la fine del set di risultati. Se la prima riga del nuovo set di righe è successiva alla fine del set di risultati, SQLFetch restituisce SQL_NO_DATA. |
| CurrRowsetStart | Numero della prima riga nel set di righe corrente. |
| LastResultRow | Numero dell'ultima riga nel set di risultati. |
| RowsetSize | Dimensioni del set di righe. |
Si supponga, ad esempio, che un set di risultati abbia 100 righe e che le dimensioni del set di righe siano 5. La tabella seguente illustra il set di righe e il codice restituito da SQLFetch per posizioni iniziali diverse.
| Set di righe corrente | Codice restituito | Nuovo set di righe | Numero di righe recuperate |
|---|---|---|---|
| Prima di iniziare | SQL_SUCCESS | Da 1 a 5 | 5 |
| Da 1 a 5 | SQL_SUCCESS | Da 6 a 10 | 5 |
| Da 52 a 56 | SQL_SUCCESS | Da 57 a 61 | 5 |
| Da 91 a 95 | SQL_SUCCESS | Da 96 a 100 | 5 |
| Da 93 a 97 | SQL_SUCCESS | da 98 a 100. Le righe 4 e 5 della matrice di stato della riga sono impostate su SQL_ROW_NOROW. | 3 |
| Da 96 a 100 | SQL_NO_DATA | Nessuno. | 0 |
| Da 99 a 100 | SQL_NO_DATA | Nessuno. | 0 |
| Dopo la fine | SQL_NO_DATA | Nessuno. | 0 |
Restituzione di dati nelle colonne associate
Quando SQLFetch restituisce ogni riga, inserisce i dati per ogni colonna associata nel buffer associato a tale colonna. Se non sono associate colonne, SQLFetch non restituisce dati, ma sposta il cursore del blocco in avanti. I dati possono comunque essere recuperati usando SQLGetData. Se il cursore è un cursore multirow, ovvero il SQL_ATTR_ROW_ARRAY_SIZE è maggiore di 1, SQLGetData può essere chiamato solo se viene restituito SQL_GD_BLOCK quando VIENE chiamato SQLGetInfo con un InfoType di SQL_GETDATA_EXTENSIONS. Per altre informazioni, vedere SQLGetData.
Per ogni colonna associata in una riga, SQLFetch esegue le operazioni seguenti:
Imposta il buffer di lunghezza/indicatore su SQL_NULL_DATA e passa alla colonna successiva se i dati sono NULL. Se i dati sono NULL e non è stato associato alcun buffer di lunghezza/indicatore, SQLFetch restituisce SQLSTATE 22002 (variabile indicatore obbligatoria ma non specificata) per la riga e procede alla riga successiva. Per informazioni su come determinare l'indirizzo del buffer di lunghezza/indicatore, vedere "Indirizzi buffer" in SQLBindCol.
Se i dati per la colonna non sono NULL, SQLFetch procede con il passaggio 2.
Se l'attributo dell'istruzione SQL_ATTR_MAX_LENGTH è impostato su un valore diverso da zero e la colonna contiene dati di tipo carattere o binari, i dati vengono troncati a SQL_ATTR_MAX_LENGTH byte.
Nota
L'attributo di istruzione SQL_ATTR_MAX_LENGTH è progettato per ridurre il traffico di rete. Viene in genere implementato dall'origine dati, che tronca i dati prima di restituirli in rete. I driver e le origini dati non sono necessari per supportarli. Pertanto, per garantire che i dati vengano troncati a una determinata dimensione, un'applicazione deve allocare un buffer di tale dimensione e specificare le dimensioni nell'argomento cbValueMax in SQLBindCol.
Converte i dati nel tipo specificato da TargetType in SQLBindCol.
Se i dati sono stati convertiti in un tipo di dati a lunghezza variabile, ad esempio carattere o binario, SQLFetch verifica se la lunghezza dei dati supera la lunghezza del buffer di dati. Se la lunghezza dei dati di tipo carattere (incluso il carattere di terminazione Null) supera la lunghezza del buffer di dati, SQLFetch tronca i dati alla lunghezza del buffer di dati meno la lunghezza di un carattere di terminazione Null. Termina quindi i dati. Se la lunghezza dei dati binari supera la lunghezza del buffer di dati, SQLFetch lo tronca alla lunghezza del buffer di dati. La lunghezza del buffer di dati viene specificata con BufferLength in SQLBindCol.
SQLFetch non tronca mai i dati convertiti in tipi di dati a lunghezza fissa. Si presuppone sempre che la lunghezza del buffer di dati sia la dimensione del tipo di dati.
Inserisce i dati convertiti (ed eventualmente troncati) nel buffer di dati. Per informazioni su come determinare l'indirizzo del buffer di dati, vedere "Indirizzi buffer" in SQLBindCol.
Inserisce la lunghezza dei dati nel buffer di lunghezza/indicatore. Se il puntatore dell'indicatore e il puntatore di lunghezza sono entrambi impostati sullo stesso buffer (come una chiamata a SQLBindCol ), la lunghezza viene scritta nel buffer per i dati validi e SQL_NULL_DATA viene scritta nel buffer per i dati NULL. Se non è stato associato alcun buffer di lunghezza/indicatore, SQLFetch non restituisce la lunghezza.
Per i dati di tipo carattere o binario, si tratta della lunghezza dei dati dopo la conversione e prima del troncamento a causa del buffer di dati troppo piccolo. Se il driver non riesce a determinare la lunghezza dei dati dopo la conversione, come accade talvolta con dati lunghi, imposta la lunghezza su SQL_NO_TOTAL. Se i dati sono stati troncati a causa dell'attributo dell'istruzione SQL_ATTR_MAX_LENGTH, il valore di questo attributo viene inserito nel buffer di lunghezza/indicatore anziché nella lunghezza effettiva . Questo è dovuto al fatto che questo attributo è progettato per troncare i dati nel server prima della conversione, in modo che il driver non abbia modo di capire qual è la lunghezza effettiva.
Per tutti gli altri tipi di dati, si tratta della lunghezza dei dati dopo la conversione; ovvero è la dimensione del tipo in cui sono stati convertiti i dati.
Per informazioni su come determinare l'indirizzo del buffer di lunghezza/indicatore, vedere "Indirizzi buffer" in SQLBindCol.
Se i dati vengono troncati durante la conversione senza perdita di cifre significative (ad esempio, il numero reale 1,234 viene troncato all'intero 1 quando viene convertito), SQLFetch restituisce SQLSTATE 01S07 (troncamento frazionario) e SQL_SUCCESS_WITH_INFO. Se i dati vengono troncati perché la lunghezza del buffer di dati è troppo piccola (ad esempio, la stringa "abcdef" viene inserita in un buffer a 4 byte), SQLFetch restituisce SQLSTATE 01004 (dati troncati) e SQL_SUCCESS_WITH_INFO. Se i dati vengono troncati a causa dell'attributo dell'istruzione SQL_ATTR_MAX_LENGTH, SQLFetch restituisce SQL_SUCCESS e non restituisce SQLSTATE 01S07 (troncamento frazionario) o SQLSTATE 01004 (dati troncati). Se i dati vengono troncati durante la conversione con una perdita di cifre significative (ad esempio, se un valore SQL_INTEGER maggiore di 100.000 è stato convertito in un SQL_C_TINYINT), SQLFetch restituisce SQLSTATE 22003 (valore numerico non compreso nell'intervallo) e SQL_ERROR (se la dimensione del set di righe è 1) o SQL_SUCCESS_WITH_INFO (se la dimensione del set di righe è maggiore di 1).
Il contenuto del buffer di dati associato e del buffer di lunghezza/indicatore non è definito se SQLFetch o SQLFetchScroll non restituisce SQL_SUCCESS o SQL_SUCCESS_WITH_INFO.
Matrice di stato riga
La matrice di stato della riga viene utilizzata per restituire lo stato di ogni riga nel set di righe. L'indirizzo di questa matrice viene specificato con l'attributo dell'istruzione SQL_ATTR_ROW_STATUS_PTR. La matrice viene allocata dall'applicazione e deve avere il numero di elementi specificato dall'attributo dell'istruzione SQL_ATTR_ROW_ARRAY_SIZE. I relativi valori vengono impostati da SQLFetch, SQLFetchScroll e SQLBulkOperations o SQLSetPos (tranne quando sono stati chiamati dopo che il cursore è stato posizionato da SQLExtendedFetch). Se il valore dell'attributo dell'istruzione SQL_ATTR_ROW_STATUS_PTR è un puntatore Null, queste funzioni non restituiscono lo stato della riga.
Il contenuto del buffer della matrice di stato della riga non è definito se SQLFetch o SQLFetchScroll non restituisce SQL_SUCCESS o SQL_SUCCESS_WITH_INFO.
Nella matrice di stato della riga vengono restituiti i valori seguenti.
| Valore della matrice di stato riga | Descrizione |
|---|---|
| SQL_ROW_SUCCESS | La riga è stata recuperata correttamente e non è stata modificata dopo l'ultimo recupero da questo set di risultati. |
| SQL_ROW_SUCCESS_WITH_INFO | La riga è stata recuperata correttamente e non è stata modificata dopo l'ultimo recupero da questo set di risultati. Tuttavia, è stato restituito un avviso relativo alla riga. |
| SQL_ROW_ERROR | Si.è verificato un errore durante il recupero della riga. |
| SQL_ROW_UPDATED[1],[2], e [3] | La riga è stata recuperata e modificata dopo l'ultimo recupero da questo set di risultati. Se la riga viene recuperata nuovamente da questo set di risultati o viene aggiornata da SQLSetPos, lo stato viene modificato nel nuovo stato della riga. |
| SQL_ROW_DELETED[3] | La riga è stata eliminata dopo l'ultimo recupero da questo set di risultati. |
| SQL_ROW_ADDED[4] | La riga è stata inserita da SQLBulkOperations. Se la riga viene recuperata nuovamente da questo set di risultati o viene aggiornata da SQLSetPos, il relativo stato viene SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | Il set di righe si sovrappone alla fine del set di risultati e non viene restituita alcuna riga corrispondente a questo elemento della matrice di stato della riga. |
[1] Per i cursori keyset, misti e dinamici, se viene aggiornato un valore di chiave, la riga di dati viene considerata eliminata e viene aggiunta una nuova riga.
[2] Alcuni driver non possono rilevare gli aggiornamenti dei dati e pertanto non possono restituire questo valore. Per determinare se un driver può rilevare gli aggiornamenti nelle righe recuperate, un'applicazione chiama SQLGetInfo con l'opzione SQL_ROW_UPDATES.
[3] SQLFetch può restituire questo valore solo quando viene combinato con le chiamate a SQLFetchScroll. Questo perché SQLFetch si sposta avanti nel set di risultati e quando viene usato esclusivamente, non esegue il refetch di alcuna riga. Poiché non vengono recuperate righe, SQLFetch non rileva le modifiche apportate alle righe recuperate in precedenza. Tuttavia, se SQLFetchScroll posiziona il cursore prima di qualsiasi riga recuperata in precedenza e SQLFetch viene usato per recuperare tali righe, SQLFetch può rilevare eventuali modifiche a tali righe.
[4] Restituito solo da SQLBulkOperations. Non impostato da SQLFetch o SQLFetchScroll.
Buffer recuperato righe
Il buffer recuperato dalle righe viene usato per restituire il numero di righe recuperate, incluse quelle per cui non sono stati restituiti dati perché si è verificato un errore durante il recupero. In altre parole, è il numero di righe per cui il valore nella matrice di stato della riga non è SQL_ROW_NOROW. L'indirizzo di questo buffer viene specificato con l'attributo dell'istruzione SQL_ATTR_ROWS_FETCHED_PTR. Il buffer viene allocato dall'applicazione. Viene impostato da SQLFetch e SQLFetchScroll. Se il valore dell'attributo dell'istruzione SQL_ATTR_ROWS_FETCHED_PTR è un puntatore Null, queste funzioni non restituiscono il numero di righe recuperate. Per determinare il numero della riga corrente nel set di risultati, un'applicazione può chiamare SQLGetStmtAttr con l'attributo SQL_ATTR_ROW_NUMBER.
Il contenuto del buffer recuperato dalle righe non è definito se SQLFetch o SQLFetchScroll non restituisce SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, tranne quando viene restituito SQL_NO_DATA, nel qual caso il valore nel buffer recuperato nelle righe è impostato su 0.
Gestione errori
Gli errori e gli avvisi possono essere applicati a singole righe o all'intera funzione. Per altre informazioni sui record di diagnostica, vedere Diagnostica e SQLGetDiagField.
Errori e avvisi sull'intera funzione
Se si verifica un errore per l'intera funzione, ad esempio SQLSTATE HYT00 (timeout scaduto) o SQLSTATE 24000 (stato cursore non valido), SQLFetch restituisce SQL_ERROR e l'istanza di SQLSTATE applicabile. Il contenuto dei buffer del set di righe non è definito e la posizione del cursore rimane invariata.
Se si applica un avviso all'intera funzione, SQLFetch restituisce SQL_SUCCESS_WITH_INFO e l'istanza di SQLSTATE applicabile. I record di stato per gli avvisi che si applicano all'intera funzione vengono restituiti prima dei record di stato applicabili alle singole righe.
Errori e avvisi in singole righe
Se si verifica un errore ( ad esempio SQLSTATE 22012 (divisione per zero)) o un avviso (ad esempio SQLSTATE 01004 (troncato dai dati)) si applica a una singola riga, SQLFetchesegue le operazioni seguenti:
Imposta l'elemento corrispondente della matrice di stato della riga su SQL_ROW_ERROR per gli errori o SQL_ROW_SUCCESS_WITH_INFO per gli avvisi.
Aggiunge zero o più record di stato che contengono SQLSTATEs per l'errore o l'avviso.
Imposta i campi dei numeri di riga e colonna nei record di stato. Se SQLFetch non è in grado di determinare un numero di riga o di colonna, imposta tale numero rispettivamente su SQL_ROW_NUMBER_UNKNOWN o SQL_COLUMN_NUMBER_UNKNOWN. Se il record di stato non si applica a una determinata colonna, SQLFetch imposta il numero di colonna su SQL_NO_COLUMN_NUMBER.
SQLFetch continua a recuperare righe fino a quando non ha recuperato tutte le righe nel set di righe. Restituisce SQL_SUCCESS_WITH_INFO a meno che non si verifichi un errore in ogni riga del set di righe (non incluse le righe con stato SQL_ROW_NOROW), nel qual caso restituisce SQL_ERROR. In particolare, se la dimensione del set di righe è 1 e si verifica un errore in tale riga, SQLFetch restituisce SQL_ERROR.
SQLFetch restituisce i record di stato nell'ordine dei numeri di riga. Ovvero restituisce tutti i record di stato per le righe sconosciute (se presenti); successivamente restituisce tutti i record di stato per la prima riga (se presente) e quindi restituisce tutti i record di stato per la seconda riga (se presente) e così via. I record di stato per ogni riga vengono ordinati in base alle normali regole per l'ordinamento dei record di stato; Per altre informazioni, vedere "Sequenza di record di stato" in SQLGetDiagField.
Descrittori e SQLFetch
Le sezioni seguenti descrivono come SQLFetch interagisce con i descrittori.
Mapping degli argomenti
Il driver non imposta alcun campo descrittore in base agli argomenti di SQLFetch.
Altri campi descrittori
I campi descrittori seguenti vengono usati da SQLFetch.
| Campo di descrizione | Desc. | Campo in | Imposta tramite |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | di autorizzazione | attributo istruzione SQL_ATTR_ROW_ARRAY_SIZE |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | di autorizzazione | attributo dell'istruzione SQL_ATTR_ROW_STATUS_PTR |
| SQL_DESC_BIND_OFFSET_PTR | ARD | di autorizzazione | Attributo dell'istruzione SQL_ATTR_ROW_BIND_OFFSET_PTR |
| SQL_DESC_BIND_TYPE | ARD | di autorizzazione | attributo di istruzione SQL_ATTR_ROW_BIND_TYPE |
| SQL_DESC_COUNT | ARD | di autorizzazione | Argomento ColumnNumber di SQLBindCol |
| SQL_DESC_DATA_PTR | ARD | record | Argomento TargetValuePtr di SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | record | argomento StrLen_or_IndPtr in SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | record | Argomento BufferLength in SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | record | argomento StrLen_or_IndPtr in SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | di autorizzazione | attributo dell'istruzione SQL_ATTR_ROWS_FETCHED_PTR |
| SQL_DESC_TYPE | ARD | record | Argomento TargetType in SQLBindCol |
Tutti i campi descrittori possono essere impostati anche tramite SQLSetDescField.
Buffer di lunghezza e indicatore separati
Le applicazioni possono associare un singolo buffer o due buffer separati che possono essere usati per contenere valori di lunghezza e indicatore. Quando un'applicazione chiama SQLBindCol, il driver imposta i campi SQL_DESC_OCTET_LENGTH_PTR e SQL_DESC_INDICATOR_PTR della ARD sullo stesso indirizzo, che viene passato nell'argomento StrLen_or_IndPtr . Quando un'applicazione chiama SQLSetDescField o SQLSetDescRec, può impostare questi due campi su indirizzi diversi.
SQLFetch determina se l'applicazione ha specificato buffer di lunghezza e indicatore separati. In questo caso, quando i dati non sono NULL, SQLFetch imposta il buffer dell'indicatore su 0 e restituisce la lunghezza nel buffer di lunghezza. Quando i dati sono NULL, SQLFetch imposta il buffer dell'indicatore su SQL_NULL_DATA e non modifica il buffer di lunghezza.
Esempio di codice
Vedere SQLBindCol, SQLColumns, SQLGetData e SQLProcedures.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di un buffer a una colonna in un set di risultati | Funzione SQLBindCol |
| Annullamento dell'elaborazione delle istruzioni | Funzione SQLCancel |
| Restituzione di informazioni su una colonna in un set di risultati | Funzione SQLDescribeCol |
| Esecuzione di un'istruzione SQL | Funzione SQLExecDirect |
| Esecuzione di un'istruzione SQL preparata | Funzione SQLExecute |
| Recupero di un blocco di dati o scorrimento di un set di risultati | Funzione SQLFetchScroll |
| Chiusura del cursore sull'istruzione | Funzione SQLFreeStmt |
| Recupero di una parte o di una colonna di dati | Funzione SQLGetData |
| Restituzione del numero di colonne del set di risultati | Funzione SQLNumResultCols |
| Preparazione di un'istruzione per l'esecuzione | Funzione SQLPrepare |