Funzione SQLExtendedFetch

  • Articolo

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'operazionedi 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'operazionedi 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.

Resi

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.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC