Funzione SQLExtendedFetch
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: Deprecata
Riepilogo
SQLExtendedFetch recupera il set di righe di dati specificato dal set di risultati e restituisce i dati per tutte le colonne associate. I set di righe possono essere specificati in una posizione assoluta o relativa o tramite segnalibro.
Nota
In ODBC 3*.x*, SQLExtendedFetch è stato sostituito da SQLFetchScroll. Le applicazioni ODBC 3*.x* non devono chiamare SQLExtendedFetch, ma devono chiamare SQLFetchScroll. Gestione driver esegue il mapping di SQLFetchScroll a SQLExtendedFetch quando si usa un driver ODBC 2*.x*. I driver ODBC 3*.x* devono supportare SQLExtendedFetch se vogliono lavorare con applicazioni ODBC 2*.x* che la chiamano. Per altre informazioni, vedere "Commenti" e cursori a blocchi, cursori scorrevoli e compatibilità con le versioni precedenti nell'Appendice G: Linee guida per la compatibilità con le versioni precedenti.
Sintassi
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Argomenti
StatementHandle
[Input] Handle di istruzione.
FetchOrientation
[Input] Tipo di recupero. Corrisponde a FetchOrientation in SQLFetchScroll.
FetchOffset
[Input] Numero della riga da recuperare. Si tratta dello stesso valore di FetchOffset in SQLFetchScroll, con un'eccezione. Quando FetchOrientation è SQL_FETCH_BOOKMARK, FetchOffset è un segnalibro a lunghezza fissa, non un offset da un segnalibro. In altre parole, SQLExtendedFetch recupera il segnalibro da questo argomento, non l'attributo dell'istruzione SQL_ATTR_FETCH_BOOKMARK_PTR. Non supporta segnalibri a lunghezza variabile e non supporta il recupero di un set di righe in corrispondenza di un offset (diverso da 0) da un segnalibro.
RowCountPtr
[Output] Puntatore a un buffer in cui restituire il numero di righe effettivamente recuperate. Questo buffer viene usato nello stesso modo del buffer specificato dall'attributo dell'istruzione SQL_ATTR_ROWS_FETCHED_PTR. Questo buffer viene usato solo da SQLExtendedFetch. Non viene usato da SQLFetch o SQLFetchScroll.
RowStatusArray
[Output] Puntatore a una matrice in cui restituire lo stato di ogni riga. Questa matrice viene usata nello stesso modo della matrice specificata dall'attributo dell'istruzione SQL_ATTR_ROW_STATUS_PTR.
Tuttavia, l'indirizzo di questa matrice non viene archiviato nel campo SQL_DESC_STATUS_ARRAY_PTR in IRD. Inoltre, questa matrice viene usata solo da SQLExtendedFetch e da SQLBulkOperations con un'operazione di SQL_ADD o SQLSetPos quando viene chiamata dopo SQLExtendedFetch. Non viene usato da SQLFetch o SQLFetchScroll e non viene usato da SQLBulkOperations o SQLSetPos quando vengono chiamati dopo SQLFetch o SQLFetchScroll. Non viene usato anche quando SQLBulkOperations con un'operazione di SQL_ADD viene chiamato prima di chiamare qualsiasi funzione di recupero. In altre parole, viene usato solo nello stato dell'istruzione S7. Non viene usato negli stati dell'istruzione S5 o S6. Per altre informazioni, vedere Transizioni di istruzioni nell'Appendice B: Tabelle di transizione dello stato ODBC.
Le applicazioni devono fornire un puntatore valido nell'argomento RowStatusArray . In caso contrario, il comportamento di SQLExtendedFetch e il comportamento delle chiamate a SQLBulkOperations o SQLSetPos dopo che un cursore è stato posizionato da SQLExtendedFetch non sono definiti.
Valori restituiti
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLExtendedFetch restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLError. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLExtendedFetch 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. 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.
| 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. Se si tratta di un valore numerico, la parte frazionaria del numero è stata troncata. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S01 | Errore nella riga | Errore durante il recupero di una o più righe. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S06 | Tentativo di recupero prima che il set di risultati restituisca il primo set di righe | Il set di righe richiesto si sovrapponeva all'inizio del set di risultati quando la posizione corrente era oltre la prima riga e FetchOrientation era SQL_PRIOR o FetchOrientation era SQL_RELATIVE con un FetchOffset negativo il cui valore assoluto era minore o uguale al SQL_ROWSET_SIZE corrente. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 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 contenenti 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 un valore di dati nel tipo di dati C specificato da TargetType in SQLBindCol. |
| 07009 | Indice descrittore non valido | La colonna 0 è stata associata a SQLBindCol 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. |
| 22002 | Variabile indicatore obbligatoria ma non fornita | I dati NULL sono stati recuperati in una colonna il cui StrLen_or_IndPtr impostato da SQLBindCol era un puntatore Null. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 22003 | Valore numerico non compreso nell'intervallo | La restituzione del valore numerico (come numerico o stringa) per una o più colonne avrebbe causato il troncamento dell'intera parte (anziché frazionaria) del numero. (La funzione restituisce SQL_SUCCESS_WITH_INFO. Per altre informazioni, vedere Linee guida per i tipi di dati intervallo e numerico 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. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 22012 | Divisione per zero | È stato restituito un valore di un'espressione aritmetica, che ha determinato la divisione per zero. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 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. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 22018 | Valore carattere non valido per la specifica del cast | 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. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 24000 | Stato del cursore non valido | StatementHandle era in uno stato eseguito, ma nessun set di risultati era associato a StatementHandle. |
| 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 SQLError 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 è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata su StatementHandle e quindi la funzione è stata chiamata nuovamente in StatementHandle. La funzione è stata chiamata 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 SQLExtendedFetch . (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 di 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) SQLExtendedFetch è stato chiamato per StatementHandle dopo la chiamata di SQLFetch o SQLFetchScroll e prima della chiamata di SQLFreeStmt con l'opzione SQL_CLOSE. (DM) SQLBulkOperations è stato chiamato per un'istruzione prima della chiamata a SQLFetch, SQLFetchScroll o SQLExtendedFetch e quindi sqlExtendedFetch è stato chiamato 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. |
| HY106 | Recupero del tipo non compreso nell'intervallo | (DM) Il valore specificato per l'argomento FetchOrientation non è valido. (Vedere "Comments.") L'argomento FetchOrientation è stato SQL_FETCH_BOOKMARK e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_OFF. Il valore dell'opzione di istruzione SQL_CURSOR_TYPE è stato SQL_CURSOR_FORWARD_ONLY e il valore dell'argomento FetchOrientation non è stato SQL_FETCH_NEXT. L'argomento FetchOrientation è stato SQL_FETCH_RESUME. |
| HY107 | Valore di riga non compreso nell'intervallo | Il valore specificato con l'opzione di istruzione SQL_CURSOR_TYPE è stato SQL_CURSOR_KEYSET_DRIVEN, ma il valore specificato con l'attributo dell'istruzione SQL_KEYSET_SIZE è maggiore di 0 e minore del valore specificato con l'attributo di istruzione SQL_ROWSET_SIZE. |
| HY111 | Valore segnalibro non valido | L'argomento FetchOrientation è stato SQL_FETCH_BOOKMARK e il segnalibro specificato nell'argomento FetchOffset non è valido. |
| 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 | Driver o origine dati non supporta il tipo di recupero specificato. 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. Questo errore si applica solo quando è stato eseguito il mapping del tipo di dati SQL della colonna a un tipo di dati SQL specifico del driver. |
| HYT00 | Timeout scaduto | Periodo di timeout della query scaduto prima che l'origine dati restituisca il set di risultati. Il periodo di timeout viene impostato tramite SQLSetStmtOption SQL_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. |
Commenti
Il comportamento di SQLExtendedFetch è identico a quello di SQLFetchScroll, con le eccezioni seguenti:
SQLExtendedFetch e SQLFetchScroll usano metodi diversi per restituire il numero di righe recuperate. SQLExtendedFetch restituisce il numero di righe recuperate in *RowCountPtr; SQLFetchScroll restituisce il numero di righe recuperate direttamente nel buffer a cui punta SQL_ATTR_ROWS_FETCHED_PTR. Per altre informazioni, vedere l'argomento RowCountPtr .
SQLExtendedFetch e SQLFetchScroll restituiscono lo stato di ogni riga in matrici diverse. Per altre informazioni, vedere l'argomento RowStatusArray .
SQLExtendedFetch e SQLFetchScroll usano metodi diversi per recuperare il segnalibro quando FetchOrientation è SQL_FETCH_BOOKMARK. SQLExtendedFetch non supporta segnalibri a lunghezza variabile o recupera i set di righe in corrispondenza di un offset diverso da 0 da un segnalibro. Per altre informazioni, vedere l'argomento FetchOffset .
SQLExtendedFetch e SQLFetchScroll usano dimensioni di set di righe diverse. SQLExtendedFetch usa il valore dell'attributo dell'istruzione SQL_ROWSET_SIZE e SQLFetchScroll usa il valore dell'attributo dell'istruzione SQL_ATTR_ROW_ARRAY_SIZE.
SQLExtendedFetch ha una semantica di gestione degli errori leggermente diversa rispetto a SQLFetchScroll. Per altre informazioni, vedere "Gestione degli errori" nella sezione "Comments" di SQLFetchScroll.
SQLExtendedFetch non supporta gli offset di associazione (attributo dell'istruzione SQL_ATTR_ROW_BIND_OFFSET_PTR).
Le chiamate a SQLExtendedFetch non possono essere combinate con chiamate a SQLFetch o SQLFetchScroll e se SQLBulkOperations viene chiamato prima che venga chiamata qualsiasi funzione di recupero, SQLExtendedFetch non può essere chiamato finché il cursore non viene chiuso e riaperto. Ovvero, SQLExtendedFetch può essere chiamato solo nello stato dell'istruzione S7. Per altre informazioni, vedere Transizioni di istruzioni nell'Appendice B: Tabelle di transizione dello stato ODBC.
Quando un'applicazione chiama SQLFetchScroll durante l'uso di un driver ODBC 2*.x*, Gestione driver esegue il mapping di questa chiamata a SQLExtendedFetch. Per altre informazioni, vedere "Driver SQLFetchScroll e ODBC 2*.x* in SQLFetchScroll.
In ODBC 2*.x*, SQLExtendedFetch è stato chiamato per recuperare più righe e SQLFetch è stato chiamato per recuperare una singola riga. In ODBC 3*.x*, invece, SQLFetch può essere chiamato per recuperare più righe.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di un buffer a una colonna in un set di risultati | Funzione SQLBindCol |
| Esecuzione di operazioni di inserimento, aggiornamento o eliminazione bulk | Funzione SQLBulkOperations |
| 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 |
| Restituzione del numero di colonne del set di risultati | Funzione SQLNumResultCols |
| Posizionamento del cursore, aggiornamento dei dati nel set di righe o aggiornamento o eliminazione di dati nel set di risultati | Funzione SQLSetPos |
| Impostazione di un attributo di istruzione | Funzione SQLSetStmtAttr |