Classe `CRecordset`

Articolo
10/12/2023

Rappresenta un set di record selezionati da un'origine dati.

Sintassi

class CRecordset : public CObject

Membri

Costruttori pubblici

Name	Descrizione
`CRecordset::CRecordset`	Costruisce un oggetto `CRecordset`. La classe derivata deve fornire un costruttore che chiama questa classe.

Metodi pubblici

Name	Descrizione
`CRecordset::AddNew`	Prepara l'aggiunta di un nuovo record. Chiamare `Update` per completare l'aggiunta.
`CRecordset::CanAppend`	Restituisce un valore diverso da zero se è possibile aggiungere nuovi record al recordset tramite la `AddNew` funzione membro.
`CRecordset::CanBookmark`	Restituisce un valore diverso da zero se il recordset supporta i segnalibri.
`CRecordset::Cancel`	Annulla un'operazione asincrona o un processo da un secondo thread.
`CRecordset::CancelUpdate`	Annulla tutti gli aggiornamenti in sospeso a causa di un'operazione `AddNew` o `Edit` .
`CRecordset::CanRestart`	Restituisce un valore diverso da zero se `Requery` è possibile chiamare per eseguire di nuovo la query del recordset.
`CRecordset::CanScroll`	Restituisce un valore diverso da zero se è possibile scorrere i record.
`CRecordset::CanTransact`	Restituisce un valore diverso da zero se l'origine dati supporta le transazioni.
`CRecordset::CanUpdate`	Restituisce un valore diverso da zero se il recordset può essere aggiornato (è possibile aggiungere, aggiornare o eliminare record).
`CRecordset::CheckRowsetError`	Chiamato per gestire gli errori generati durante il recupero dei record.
`CRecordset::Close`	Chiude il recordset e l'oggetto ODBC `HSTMT` associato.
`CRecordset::Delete`	Elimina il record corrente dal recordset. È necessario scorrere in modo esplicito fino a un altro record dopo l'eliminazione.
`CRecordset::DoBulkFieldExchange`	Chiamato per scambiare righe bulk di dati dall'origine dati al recordset. Implementa lo scambio di campi dei record in blocco (RFX bulk).
`CRecordset::DoFieldExchange`	Chiamato per scambiare dati (in entrambe le direzioni) tra i membri dati del campo del recordset e il record corrispondente nell'origine dati. Implementa lo scambio di campi di record (RFX).
`CRecordset::Edit`	Prepara le modifiche al record corrente. Chiamare `Update` per completare la modifica.
`CRecordset::FlushResultSet`	Restituisce un valore diverso da zero se è presente un altro set di risultati da recuperare quando si usa una query predefinita.
`CRecordset::GetBookmark`	Assegna il valore del segnalibro di un record all'oggetto parametro.
`CRecordset::GetDefaultConnect`	Chiamato per ottenere il stringa di connessione predefinito.
`CRecordset::GetDefaultSQL`	Chiamato per ottenere la stringa SQL predefinita da eseguire.
`CRecordset::GetFieldValue`	Restituisce il valore di un campo in un recordset.
`CRecordset::GetODBCFieldCount`	Restituisce il numero di campi nell'oggetto recordset.
`CRecordset::GetODBCFieldInfo`	Restituisce tipi specifici di informazioni sui campi di un recordset.
`CRecordset::GetRecordCount`	Restituisce il numero di record nel recordset.
`CRecordset::GetRowsetSize`	Restituisce il numero di record che si desidera recuperare durante un singolo recupero.
`CRecordset::GetRowsFetched`	Restituisce il numero effettivo di righe recuperate durante un recupero.
`CRecordset::GetRowStatus`	Restituisce lo stato della riga dopo un recupero.
`CRecordset::GetSQL`	Ottiene la stringa SQL utilizzata per selezionare i record per il recordset.
`CRecordset::GetStatus`	Ottiene lo stato del recordset: indice del record corrente e indica se è stato ottenuto un conteggio finale dei record.
`CRecordset::GetTableName`	Ottiene il nome della tabella su cui si basa il recordset.
`CRecordset::IsBOF`	Restituisce un valore diverso da zero se il recordset è stato posizionato prima del primo record. Non esiste alcun record corrente.
`CRecordset::IsDeleted`	Restituisce un valore diverso da zero se il recordset è posizionato su un record eliminato.
`CRecordset::IsEOF`	Restituisce un valore diverso da zero se il recordset è stato posizionato dopo l'ultimo record. Non esiste alcun record corrente.
`CRecordset::IsFieldDirty`	Restituisce un valore diverso da zero se il campo specificato nel record corrente è stato modificato.
`CRecordset::IsFieldNull`	Restituisce un valore diverso da zero se il campo specificato nel record corrente è Null (non ha alcun valore).
`CRecordset::IsFieldNullable`	Restituisce un valore diverso da zero se il campo specificato nel record corrente può essere impostato su Null (senza valore).
`CRecordset::IsOpen`	Restituisce un valore diverso da zero se `Open` è stato chiamato in precedenza.
`CRecordset::Move`	Posiziona il recordset su un numero specificato di record dal record corrente in entrambe le direzioni.
`CRecordset::MoveFirst`	Posiziona il record corrente sul primo record del recordset. Eseguire il test per `IsBOF` primo.
`CRecordset::MoveLast`	Posiziona il record corrente sull'ultimo record o sull'ultimo set di righe. Eseguire il test per `IsEOF` primo.
`CRecordset::MoveNext`	Posiziona il record corrente sul record successivo o sul set di righe successivo. Eseguire il test per `IsEOF` primo.
`CRecordset::MovePrev`	Posiziona il record corrente sul record precedente o sul set di righe precedente. Eseguire il test per `IsBOF` primo.
`CRecordset::OnSetOptions`	Chiamato per impostare le opzioni (utilizzate nella selezione) per l'istruzione ODBC specificata.
`CRecordset::OnSetUpdateOptions`	Chiamato per impostare le opzioni (utilizzate per l'aggiornamento) per l'istruzione ODBC specificata.
`CRecordset::Open`	Apre il recordset recuperando la tabella o eseguendo la query rappresentata dal recordset.
`CRecordset::RefreshRowset`	Aggiorna i dati e lo stato delle righe specificate.
`CRecordset::Requery`	Esegue di nuovo la query del recordset per aggiornare i record selezionati.
`CRecordset::SetAbsolutePosition`	Posiziona il recordset sul record corrispondente al numero di record specificato.
`CRecordset::SetBookmark`	Posiziona il recordset sul record specificato dal segnalibro.
`CRecordset::SetFieldDirty`	Contrassegna il campo specificato nel record corrente come modificato.
`CRecordset::SetFieldNull`	Imposta il valore del campo specificato nel record corrente su null (senza alcun valore).
`CRecordset::SetLockingMode`	Imposta la modalità di blocco su blocco "ottimistico" (impostazione predefinita) o "pessimistico". Determina la modalità di blocco dei record per gli aggiornamenti.
`CRecordset::SetParamNull`	Imposta il parametro specificato su null (senza valore).
`CRecordset::SetRowsetCursorPosition`	Posiziona il cursore sulla riga specificata all'interno del set di righe.
`CRecordset::SetRowsetSize`	Specifica il numero di record che si desidera recuperare durante un recupero.
`CRecordset::Update`	Completa un'operazione `AddNew` o `Edit` salvando i dati nuovi o modificati nell'origine dati.

Membri dati pubblici

Name	Descrizione
`CRecordset::m_hstmt`	Contiene l'handle di istruzione ODBC per il recordset. Digitare `HSTMT`.
`CRecordset::m_nFields`	Contiene il numero di membri dati del campo nel recordset. Digitare `UINT`.
`CRecordset::m_nParams`	Contiene il numero di membri dati dei parametri nel recordset. Digitare `UINT`.
`CRecordset::m_pDatabase`	Contiene un puntatore all'oggetto tramite il quale il recordset è connesso a un'origine `CDatabase` dati.
`CRecordset::m_strFilter`	Contiene un oggetto `CString` che specifica una clausola SQL (Structured Query Language). `WHERE` Utilizzato come filtro per selezionare solo i record che soddisfano determinati criteri.
`CRecordset::m_strSort`	Contiene un oggetto `CString` che specifica una clausola SQL `ORDER BY` . Consente di controllare la modalità di ordinamento dei record.

Osservazioni:

Noti come "recordset", CRecordset gli oggetti vengono in genere usati in due forme: dynaset e snapshot. Un dynaset rimane sincronizzato con gli aggiornamenti dei dati eseguiti da altri utenti. Uno snapshot è una visualizzazione statica dei dati. Ogni maschera rappresenta un set di record fissi al momento dell'apertura del recordset. Quando si scorre un record in un dynaset, riflette le modifiche apportate al record, da altri utenti o da altri recordset nell'applicazione.

Nota

Se si usano le classi DAO (Data Access Objects) anziché le classi OPEN Database Connessione ivity (ODBC), usare invece la classe CDaoRecordset . Per altre informazioni, vedere Panoramica: Programmazione del database.

Per usare entrambi i tipi di recordset, in genere si deriva una classe recordset specifica dell'applicazione da CRecordset. I recordset selezionano i record da un'origine dati ed è quindi possibile:

Scorrere i record.
Aggiornare i record e specificare una modalità di blocco.
Filtrare il recordset per vincolare i record selezionati da quelli disponibili nell'origine dati.
Ordinare il recordset.
Parametrizzare il recordset per personalizzarne la selezione con informazioni non note fino al runtime.

Per usare la classe, aprire un database e costruire un oggetto recordset, passando il costruttore un puntatore all'oggetto CDatabase . Chiamare quindi la funzione membro del Open recordset, in cui è possibile specificare se l'oggetto è un dynaset o uno snapshot. La chiamata Open seleziona i dati dall'origine dati. Dopo l'apertura dell'oggetto recordset, utilizzare le funzioni membro e i membri dati per scorrere i record e usarli. Le operazioni disponibili dipendono dal fatto che l'oggetto sia un dynaset o uno snapshot, sia aggiornabile o di sola lettura (dipende dalla funzionalità dell'origine dati Open Database Connessione ivity (ODBC) e dal fatto che sia stato implementato il recupero delle righe bulk. Per aggiornare i record che potrebbero essere stati modificati o aggiunti dopo la Open chiamata, chiamare la funzione membro dell'oggetto Requery . Chiamare la funzione membro dell'oggetto Close ed eliminare definitivamente l'oggetto al termine dell'operazione.

In una classe derivata CRecordset , lo scambio di campi di record (RFX) o lo scambio di campi di record bulk (RFX bulk) viene usato per supportare la lettura e l'aggiornamento dei campi di record.

Per altre informazioni sui recordset e sullo scambio di campi di record, vedere gli articoli Panoramica: Programmazione del database, Recordset (ODBC), Recordset: Recupero di record in blocco (ODBC)e Scambio di campi di record (RFX). Per informazioni su dynaset e snapshot, vedere gli articoli Dynaset e Snapshot.

Gerarchia di ereditarietà

CObject

CRecordset

Requisiti

Intestazione:afxdb.h

`CRecordset::AddNew`

Prepara l'aggiunta di un nuovo record alla tabella.

virtual void AddNew();

Osservazioni:

È necessario chiamare la Requery funzione membro per visualizzare il record appena aggiunto. I campi del record sono inizialmente Null. Nella terminologia del database Null significa "senza valore" e non è uguale a NULL in C++. Per completare l'operazione, è necessario chiamare la Update funzione membro. Update salva le modifiche apportate all'origine dati.

Nota

Se è stato implementato il recupero delle righe bulk, non è possibile chiamare AddNew. In questo modo verrà restituita un'asserzione non riuscita. Sebbene la classe CRecordset non fornisca un meccanismo per l'aggiornamento di righe bulk di dati, è possibile scrivere funzioni personalizzate usando la funzione SQLSetPosAPI ODBC . Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

AddNew prepara un nuovo record vuoto utilizzando i membri dati del campo del recordset. Dopo aver chiamato AddNew, impostare i valori desiderati nei membri dati del campo del recordset. (Non è necessario chiamare il Modificare la funzione membro per questo scopo; utilizzare Edit solo per i record esistenti. Quando si chiama Update, i valori modificati nei membri dati del campo vengono salvati nell'origine dati.

Attenzione

Se si scorre fino a un nuovo record prima di chiamare Update, il nuovo record viene perso e non viene visualizzato alcun avviso.

Se l'origine dati supporta le transazioni, è possibile eseguire la AddNew chiamata come parte di una transazione. Per altre informazioni sulle transazioni, vedere classe CDatabase. Chiamare prima di CDatabase::BeginTrans chiamare AddNew.

Nota

Per i dynaset, i nuovi record vengono aggiunti al recordset come ultimo record. I record aggiunti non vengono aggiunti agli snapshot; è necessario chiamare Requery per aggiornare il recordset.

Non è possibile chiamare AddNew per un recordset la cui Open funzione membro non è stata chiamata. Viene CDBException generata un'eccezione se si chiama AddNew per un recordset a cui non è possibile accodare. È possibile determinare se il recordset è aggiornabile chiamando CanAppend.

Per altre informazioni, vedere gli articoli seguenti: Recordset: How Recordsets Update Records (ODBC), Recordset: Adding, Updating, and Deleting Records (ODBC), and Transaction (ODBC).

Esempio

vedere Transazione: esecuzione di una transazione in un oggetto Recordset (ODBC).See Transaction: Performing a Transaction in a Recordset (ODBC).

`CRecordset::CanAppend`

Determina se il recordset aperto in precedenza consente di aggiungere nuovi record.

BOOL CanAppend() const;

Valore restituito

Diverso da zero se il recordset consente l'aggiunta di nuovi record; in caso contrario, 0. CanAppend restituisce 0 se l'oggetto recordset è stato aperto come di sola lettura.

`CRecordset::CanBookmark`

Determina se il recordset consente di contrassegnare i record tramite segnalibri.

BOOL CanBookmark() const;

Valore restituito

Diverso da zero se il recordset supporta segnalibri; in caso contrario, 0.

Osservazioni:

Questa funzione è indipendente dall'opzione CRecordset::useBookmarks nel dwOptions parametro della Open funzione membro. CanBookmark indica se il driver ODBC e il tipo di cursore specificati supportano i segnalibri. CRecordset::useBookmarks indica se i segnalibri saranno disponibili, purché siano supportati.

Nota

I segnalibri non sono supportati nei recordset forward-only.

Per altre informazioni sui segnalibri e sulla navigazione dei recordset, vedere gli articoli Recordset: Segnalibri e posizioni assolute (ODBC) e Recordset: Scorrimento (ODBC).

`CRecordset::Cancel`

Richiede che l'origine dati annulla un'operazione asincrona in corso o un processo da un secondo thread.

void Cancel();

Osservazioni:

Le classi ODBC MFC non usano più l'elaborazione asincrona; per eseguire un'operazione asincrona, è necessario chiamare direttamente la funzione SQLSetConnectOptionAPI ODBC . Per altre informazioni, vedere "Esecuzione di funzioni in modo asincrono" nella Guida per programmatori di ODBC SDK.

`CRecordset::CancelUpdate`

Annulla tutti gli aggiornamenti in sospeso, causati da un'operazione Edit o AddNew , prima Update di essere chiamato.

void CancelUpdate();

Osservazioni:

Nota

Questa funzione membro non è applicabile ai recordset che usano il recupero di righe bulk, poiché tali recordset non possono chiamare Edit, AddNewo Update. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

Se il controllo automatico dei campi dirty è abilitato, CancelUpdate ripristinerà le variabili membro ai valori che avevano precedentemente Edit o AddNew è stato chiamato. In caso contrario, le modifiche al valore rimarranno. Per impostazione predefinita, il controllo dei campi automatico viene abilitato all'apertura del recordset. Per disabilitarla, è necessario specificare CRecordset::noDirtyFieldCheck nel dwOptions parametro della funzione membro Open .

Per altre informazioni sull'aggiornamento dei dati, vedere Recordset: Aggiunta, aggiornamento ed eliminazione di record (ODBC).

`CRecordset::CanRestart`

Determina se il recordset consente di riavviare la query (per aggiornarne i record) chiamando la Requery funzione membro.

BOOL CanRestart() const;

Valore restituito

Diverso da zero se la requery è consentita; in caso contrario, 0.

`CRecordset::CanScroll`

Determina se il recordset consente lo scorrimento.

BOOL CanScroll() const;

Valore restituito

Diverso da zero se il recordset consente lo scorrimento; in caso contrario, 0.

Osservazioni:

Per altre informazioni sullo scorrimento, vedere Recordset: Scorrimento (ODBC).For more information about scrolling, see Recordset: Scrolling (ODBC).

`CRecordset::CanTransact`

Determina se il recordset consente transazioni.

BOOL CanTransact() const;

Valore restituito

Diverso da zero se il recordset consente transazioni; in caso contrario, 0.

Osservazioni:

Per altre informazioni, vedere Transaction (ODBC).

`CRecordset::CanUpdate`

Determina se è possibile aggiornare il recordset.

BOOL CanUpdate() const;

Valore restituito

Diverso da zero se il recordset può essere aggiornato; in caso contrario, 0.

Osservazioni:

Un recordset potrebbe essere di sola lettura se l'origine dati sottostante è di sola lettura o se è stata specificata CRecordset::readOnly nel dwOptions parametro quando è stato aperto il recordset.

`CRecordset::CheckRowsetError`

Chiamato per gestire gli errori generati durante il recupero dei record.

virtual void CheckRowsetError(RETCODE nRetCode);

Parametri

nRetCode
Codice restituito da una funzione API ODBC. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

Questa funzione membro virtuale gestisce gli errori che si verificano quando vengono recuperati i record ed è utile durante il recupero delle righe bulk. È consigliabile prendere in considerazione l'override CheckRowsetError per implementare la gestione degli errori personalizzata.

CheckRowsetError viene chiamato automaticamente in un'operazione di navigazione cursore, ad esempio Open, Requeryo qualsiasi Move operazione. Viene passato il valore restituito della funzione SQLExtendedFetchAPI ODBC . Nella tabella seguente sono elencati i valori possibili per il nRetCode parametro .

nRetCode	Descrizione
`SQL_SUCCESS`	La funzione è stata completata correttamente; non sono disponibili informazioni aggiuntive.
`SQL_SUCCESS_WITH_INFO`	La funzione è stata completata correttamente, possibilmente con un errore non irreversibile. È possibile ottenere informazioni aggiuntive chiamando `SQLError`.
`SQL_NO_DATA_FOUND`	Tutte le righe del set di risultati sono state recuperate.
`SQL_ERROR`	La funzione non è riuscita. È possibile ottenere informazioni aggiuntive chiamando `SQLError`.
`SQL_INVALID_HANDLE`	La funzione non è riuscita a causa di un handle di ambiente, un handle di connessione o un handle di istruzione non valido. Indica un errore di programmazione. Nessuna informazione aggiuntiva è disponibile da `SQLError`.
`SQL_STILL_EXECUTING`	Una funzione avviata in modo asincrono è ancora in esecuzione. Per impostazione predefinita, MFC non passerà mai questo valore a `CheckRowsetError`; MFC continuerà a chiamare `SQLExtendedFetch` fino a quando non restituisce `SQL_STILL_EXECUTING`più .

Per altre informazioni su SQLError, vedere Windows SDK. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

`CRecordset::Close`

Chiude il recordset.

virtual void Close();

Osservazioni:

ODBC HSTMT e tutta la memoria allocata per il recordset vengono deallocate. In genere dopo aver chiamato Close, si elimina l'oggetto recordset C++ se è stato allocato con new.

È possibile chiamare di nuovo dopo aver chiamato OpenClose. In questo modo è possibile riutilizzare l'oggetto recordset. L'alternativa consiste nel chiamare Requery.

Esempio

// Construct a snapshot object
CCustomer rsCustSet(NULL);

if (!rsCustSet.Open())
return;

// Use the snapshot ...

// Close the snapshot
rsCustSet.Close();

// Destructor is called when the function exits

`CRecordset::CRecordset`

Costruisce un oggetto CRecordset.

CRecordset(CDatabase* pDatabase = NULL);

Parametri

pDatabase
Contiene un puntatore a un CDatabase oggetto o al valore NULL. Se non NULL e la CDatabase funzione membro dell'oggetto Open non è stata chiamata per connetterla all'origine dati, il recordset tenta di aprirlo per conto dell'utente durante la propria Open chiamata. Se si passa NULL, un CDatabase oggetto viene costruito e connesso usando le informazioni sull'origine dati specificate quando è stata derivata la classe recordset con ClassWizard.

Osservazioni:

È possibile usare CRecordset direttamente o derivare una classe specifica dell'applicazione da CRecordset. È possibile usare ClassWizard per derivare le classi recordset.

Nota

Una classe derivata deve fornire il proprio costruttore. Nel costruttore della classe derivata chiamare il costruttore CRecordset::CRecordset, passando i parametri appropriati.

Passare NULL al costruttore del recordset per avere un CDatabase oggetto costruito e connesso automaticamente. Si tratta di una abbreviata utile che non richiede di costruire e connettere un CDatabase oggetto prima di costruire il recordset.

Esempio

Per altre informazioni, vedere Recordset: Dichiarazione di una classe per una tabella (ODBC).

`CRecordset::Delete`

Elimina il record corrente.

virtual void Delete();

Osservazioni:

Dopo l'eliminazione, i membri dati del campo del recordset vengono impostati su un valore Null ed è necessario chiamare in modo esplicito una delle Move funzioni per rimuovere il record eliminato. Una volta spostato il record eliminato, non è possibile tornare al record. Se l'origine dati supporta le transazioni, è possibile effettuare la Delete parte di chiamata di una transazione. Per altre informazioni, vedere Transaction (ODBC).

Nota

Se è stato implementato il recupero delle righe bulk, non è possibile chiamare Delete. In questo modo verrà restituita un'asserzione non riuscita. Sebbene la classe CRecordset non fornisca un meccanismo per l'aggiornamento di righe bulk di dati, è possibile scrivere funzioni personalizzate usando la funzione SQLSetPosAPI ODBC . Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

Attenzione

Il recordset deve essere aggiornabile e deve essere presente un record valido nel recordset quando si chiama Delete. In caso contrario, si verifica un errore. Ad esempio, se si elimina un record ma non si scorre verso un nuovo record prima di chiamare Delete di nuovo, Delete genera un'eccezione CDBException.

A differenza di AddNew e Edit, una chiamata a Delete non è seguita da una chiamata a Update. Se una Delete chiamata ha esito negativo, i membri dati del campo vengono lasciati invariati.

Esempio

In questo esempio viene illustrato un recordset creato nel frame di una funzione. Nell'esempio si presuppone l'esistenza di m_dbCust, una variabile membro di tipo CDatabase già connessa all'origine dati.

// Create a derived CRecordset object
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if (rsCustSet.IsEOF() || !rsCustSet.CanUpdate() ||
   !rsCustSet.CanTransact())
{
   return;
}

m_dbCust.BeginTrans();

// Perhaps scroll to a new record...
// Delete the current record
rsCustSet.Delete();

// Finished commands for this transaction
if (IDYES == AfxMessageBox(_T("Commit transaction?"), MB_YESNO))
m_dbCust.CommitTrans();
else // User changed mind
m_dbCust.Rollback();

`CRecordset::DoBulkFieldExchange`

Chiamato per scambiare righe bulk di dati dall'origine dati al recordset. Implementa lo scambio di campi dei record in blocco (RFX bulk).

virtual void DoBulkFieldExchange(CFieldExchange* pFX);

Parametri

pFX
Puntatore a un oggetto CFieldExchange. Il framework avrà già configurato questo oggetto per specificare un contesto per l'operazione di scambio dei campi.

Osservazioni:

Quando viene implementato il recupero di righe bulk, il framework chiama questa funzione membro per trasferire automaticamente i dati dall'origine dati all'oggetto recordset. DoBulkFieldExchange associa anche i membri dei dati dei parametri, se presenti, ai segnaposto dei parametri nella stringa dell'istruzione SQL per la selezione del recordset.

Se il recupero delle righe bulk non è implementato, il framework chiama DoFieldExchange. Per implementare il recupero delle righe bulk, è necessario specificare l'opzione CRecordset::useMultiRowFetch del parametro dwOptions nella Open funzione membro.

Nota

DoBulkFieldExchange è disponibile solo se si usa una classe derivata da CRecordset. Se è stato creato un oggetto recordset direttamente da CRecordset, è necessario chiamare la GetFieldValue funzione membro per recuperare i dati.

Lo scambio di campi dei record bulk (RFX bulk) è simile allo scambio di campi di record (RFX). I dati vengono trasferiti automaticamente dall'origine dati all'oggetto recordset. Tuttavia, non è possibile chiamare AddNew, Edit, Deleteo Update per trasferire di nuovo le modifiche all'origine dati. La classe CRecordset attualmente non fornisce un meccanismo per l'aggiornamento di righe bulk di dati. Tuttavia, è possibile scrivere funzioni personalizzate usando la funzione SQLSetPosAPI ODBC .

ClassWizard non supporta lo scambio di campi di record bulk; pertanto, è necessario eseguire l'override manualmente DoBulkFieldExchange scrivendo chiamate alle funzioni RFX bulk. Per altre informazioni su queste funzioni, vedere Funzioni di Scambio campi record.

Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC). Per informazioni correlate, vedere Record Field Exchange (RFX).

`CRecordset::DoFieldExchange`

Chiamato per scambiare dati (in entrambe le direzioni) tra i membri dati del campo del recordset e il record corrispondente nell'origine dati. Implementa lo scambio di campi di record (RFX).

virtual void DoFieldExchange(CFieldExchange* pFX);

Parametri

pFX
Puntatore a un oggetto CFieldExchange. Il framework avrà già configurato questo oggetto per specificare un contesto per l'operazione di scambio dei campi.

Osservazioni:

Quando il recupero delle righe bulk non è implementato, il framework chiama questa funzione membro per scambiare automaticamente i dati tra i membri dati di campo dell'oggetto recordset e le colonne corrispondenti del record corrente nell'origine dati. DoFieldExchange associa anche i membri dei dati dei parametri, se presenti, ai segnaposto dei parametri nella stringa dell'istruzione SQL per la selezione del recordset.

Se viene implementato il recupero di righe bulk, il framework chiama DoBulkFieldExchange. Per implementare il recupero delle righe bulk, è necessario specificare l'opzione CRecordset::useMultiRowFetch del dwOptions parametro nella Open funzione membro.

Nota

DoFieldExchange è disponibile solo se si usa una classe derivata da CRecordset. Se è stato creato un oggetto recordset direttamente da CRecordset, è necessario chiamare la funzione membro GetFieldValue per recuperare i dati.

Lo scambio di dati di campo, denominato scambio di campi record (RFX), funziona in entrambe le direzioni: dai membri dati di campo dell'oggetto recordset ai campi del record nell'origine dati e dal record nell'origine dati all'oggetto recordset.

L'unica azione da eseguire normalmente per implementare DoFieldExchange per la classe recordset derivata consiste nel creare la classe con ClassWizard e specificare i nomi e i tipi di dati dei membri dati del campo. È anche possibile aggiungere codice a ciò che ClassWizard scrive per specificare i membri dei dati dei parametri o per gestire le colonne associate in modo dinamico. Per altre informazioni, vedere Recordset: Binding dinamico di colonne di dati (ODBC).

Quando si dichiara la classe recordset derivata con ClassWizard, la procedura guidata scrive un override di DoFieldExchange , simile all'esempio seguente:

void CCustomer::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputColumn);
   // Macros such as RFX_Text() and RFX_Int() are dependent on the
   // type of the member variable, not the type of the field in the database.
   // ODBC will try to automatically convert the column value to the requested type
   RFX_Long(pFX, _T("[CustomerID]"), m_CustomerID);
   RFX_Text(pFX, _T("[ContactFirstName]"), m_ContactFirstName);
   RFX_Text(pFX, _T("[PostalCode]"), m_PostalCode);
   RFX_Text(pFX, _T("[L_Name]"), m_L_Name);
   RFX_Long(pFX, _T("[BillingID]"), m_BillingID);

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param"), m_strParam);
}

Per altre informazioni sulle funzioni RFX, vedere Funzioni di scambio dei campi di record.

Per altri esempi e dettagli su DoFieldExchange, vedere Record Field Exchange: Funzionamento di RFX. Per informazioni generali su RFX, vedere Record Field Exchange.

`CRecordset::Edit`

Consente di apportare modifiche al record corrente.

virtual void Edit();

Osservazioni:

Dopo aver chiamato Edit, è possibile modificare i membri dei dati del campo reimpostando direttamente i valori. L'operazione viene completata quando si chiama la Update funzione membro per salvare le modifiche nell'origine dati.

Nota

Se è stato implementato il recupero delle righe bulk, non è possibile chiamare Edit. In questo modo verrà restituita un'asserzione non riuscita. Sebbene la classe CRecordset non fornisca un meccanismo per l'aggiornamento di righe bulk di dati, è possibile scrivere funzioni personalizzate usando la funzione SQLSetPosAPI ODBC . Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

Edit salva i valori dei membri dati del recordset. Se si chiama , apportare modifiche, chiamare EditEdit di nuovo i valori del record in base a ciò che erano prima della prima Edit chiamata.

In alcuni casi, è possibile aggiornare una colonna rendendola Null (che non contiene dati). A tale scopo, chiamare SetFieldNull con un parametro true per contrassegnare il campo Null. In questo modo la colonna verrà aggiornata. Se si vuole che un campo venga scritto nell'origine dati anche se il relativo valore non è stato modificato, chiamare SetFieldDirty con un parametro TRUE. Questa operazione funziona anche se il campo ha il valore Null.

Se l'origine dati supporta le transazioni, è possibile effettuare la Edit parte di chiamata di una transazione. Chiamare CDatabase::BeginTrans prima di chiamare Edit e dopo l'apertura del recordset. Inoltre, la chiamata non sostituisce la chiamata CDatabase::CommitTransUpdate per completare l'operazione Edit . Per altre informazioni sulle transazioni, vedere classe CDatabase.

A seconda della modalità di blocco corrente, il record da aggiornare può essere bloccato finché Edit non si chiama Update o si scorre su un altro record oppure può essere bloccato solo durante la Edit chiamata. È possibile modificare la modalità di blocco con SetLockingMode.

Il valore precedente del record corrente viene ripristinato se si scorre fino a un nuovo record prima di chiamare Update. Viene CDBException generata un'eccezione se si chiama Edit per un recordset che non può essere aggiornato o se non è presente alcun record corrente.

Per altre informazioni, vedere gli articoli Transaction (ODBC) e Recordset: Locking Records (ODBC).

Esempio

// To edit a record, first set up the edit buffer
rsCustSet.Edit();

// Then edit field data members for the record
rsCustSet.m_BillingID = 2795;
rsCustSet.m_ContactFirstName = _T("Jones Mfg");

// Finally, complete the operation
if (!rsCustSet.Update())
{
   // Handle the failure to update
   AfxMessageBox(_T("Couldn't update record!"));
}

`CRecordset::FlushResultSet`

Recupera il set di risultati successivo di una query predefinita (stored procedure), se sono presenti più set di risultati.

BOOL FlushResultSet();

Valore restituito

Diverso da zero se sono presenti più set di risultati da recuperare; in caso contrario, 0.

Osservazioni:

È consigliabile chiamare FlushResultSet solo al termine del cursore nel set di risultati corrente. Quando si recupera il set di risultati successivo chiamando FlushResultSet, il cursore non è valido in tale set di risultati; è necessario chiamare la MoveNext funzione membro dopo aver chiamato FlushResultSet.

Se una query predefinita usa un parametro di output o parametri di input/output, è necessario chiamare FlushResultSet fino a quando non restituisce FALSE(il valore 0), per ottenere questi valori di parametro.

FlushResultSet chiama la funzione SQLMoreResultsAPI ODBC . Se SQLMoreResults restituisce SQL_ERROR o SQL_INVALID_HANDLE, genererà FlushResultSet un'eccezione. Per altre informazioni su SQLMoreResults, vedere Windows SDK.

La stored procedure deve avere campi associati se si desidera chiamare FlushResultSet.

Esempio

Il codice seguente presuppone che COutParamRecordset sia un CRecordsetoggetto derivato da -basato su una query predefinita con un parametro di input e un parametro di output e che abbia più set di risultati. Si noti la struttura dell'override DoFieldExchange .

// DoFieldExchange override
//
// Only necessary to handle parameter bindings.
// Don't use CRecordset-derived class with bound
// fields unless all result sets have same schema
// OR there is conditional binding code.
void CCourses::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputParam);
   RFX_Long(pFX, _T("Param1"), m_nCountParam);
   // The "Param1" name here is a dummy name 
   // that is never used

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param2"), m_strNameParam);
   // The "Param2" name here is a dummy name 
   // that is never used
}

// Assume db is an already open CDatabase object
CCourses rs(&m_dbCust);
rs.m_strNameParam = _T("History");

// Get the first result set
// NOTE: SQL Server requires forwardOnly cursor 
//       type for multiple rowset returning stored 
//       procedures
rs.Open(CRecordset::forwardOnly,
   _T("{? = CALL GetCourses( ? )}"),
   CRecordset::readOnly);

// Loop through all the data in the first result set
while (!rs.IsEOF())
{
   CString strFieldValue;
   for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
   {
      rs.GetFieldValue(nIndex, strFieldValue);

      // TO DO: Use field value string.
   }
   rs.MoveNext();
}

// Retrieve other result sets...
while (rs.FlushResultSet())
{
   // must call MoveNext because cursor is invalid
   rs.MoveNext();

   while (!rs.IsEOF())
   {
      CString strFieldValue;
      for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
      {
         rs.GetFieldValue(nIndex, strFieldValue);

         // TO DO: Use field value string.
      }
      rs.MoveNext();
   }
}


// All result sets have been flushed. Cannot
// use the cursor, but the output parameter,
// m_nCountParam, has now been written.
// Note that m_nCountParam is not valid until
// CRecordset::FlushResultSet has returned FALSE,
// indicating no more result sets will be returned.

// TO DO: Use m_nCountParam

// Cleanup
rs.Close();

`CRecordset::GetBookmark`

Ottiene il valore del segnalibro per il record corrente.

void GetBookmark(CDBVariant& varBookmark);

Parametri

varBookmark
Riferimento a un CDBVariant oggetto che rappresenta il segnalibro nel record corrente.

Osservazioni:

Per determinare se i segnalibri sono supportati nel recordset, chiamare CanBookmark. Per rendere disponibili i segnalibri se supportati, è necessario impostare l'opzione CRecordset::useBookmarks nel dwOptions parametro della Open funzione membro.

Nota

Se i segnalibri non sono supportati o non sono disponibili, la chiamata GetBookmark genererà un'eccezione. I segnalibri non sono supportati nei recordset forward-only.

GetBookmark assegna il valore del segnalibro per il record corrente a un CDBVariant oggetto . Per tornare a tale record in qualsiasi momento dopo il passaggio a un record diverso, chiamare SetBookmark con l'oggetto corrispondente CDBVariant .

Nota

Dopo determinate operazioni del recordset, i segnalibri potrebbero non essere più validi. Ad esempio, se si chiama GetBookmark seguito da Requery, potrebbe non essere possibile tornare al record con SetBookmark. Chiamare CDatabase::GetBookmarkPersistence per verificare se è possibile chiamare SetBookmarkin modo sicuro .

Per altre informazioni sui segnalibri e sulla navigazione dei recordset, vedere gli articoli Recordset: Segnalibri e posizioni assolute (ODBC) e Recordset: Scorrimento (ODBC).

`CRecordset::GetDefaultConnect`

Chiamato per ottenere il stringa di connessione predefinito.

virtual CString GetDefaultConnect();

Valore restituito

Oggetto CString contenente il stringa di connessione predefinito.

Osservazioni:

Il framework chiama questa funzione membro per ottenere il stringa di connessione predefinito per l'origine dati su cui si basa il recordset. ClassWizard implementa questa funzione identificando la stessa origine dati usata in ClassWizard per ottenere informazioni su tabelle e colonne. Probabilmente sarà utile basarsi su questa connessione predefinita durante lo sviluppo dell'applicazione. Tuttavia, la connessione predefinita potrebbe non essere appropriata per gli utenti dell'applicazione. In questo caso, è necessario rimplementare questa funzione, ignorando ClassWizardla versione di . Per altre informazioni sulle stringa di connessione, vedere Origine dati (ODBC).

`CRecordset::GetDefaultSQL`

Chiamato per ottenere la stringa SQL predefinita da eseguire.

virtual CString GetDefaultSQL();

Valore restituito

Oggetto CString contenente l'istruzione SQL predefinita.

Osservazioni:

Il framework chiama questa funzione membro per ottenere l'istruzione SQL predefinita su cui si basa il recordset. Potrebbe trattarsi di un nome di tabella o di un'istruzione SQL SELECT .

L'istruzione SQL predefinita viene definita indirettamente dichiarando la classe recordset con ClassWizarded ClassWizard esegue automaticamente questa attività.

Se è necessaria la stringa dell'istruzione SQL per il proprio uso, chiamare GetSQL, che restituisce l'istruzione SQL usata per selezionare i record del recordset all'apertura. È possibile modificare la stringa SQL predefinita nell'override della classe di GetDefaultSQL. Ad esempio, è possibile specificare una chiamata a una query predefinita usando un'istruzione CALL . Si noti, tuttavia, che se si modifica GetDefaultSQL, è necessario modificare m_nFields anche in modo che corrisponda al numero di colonne nell'origine dati.

Per altre informazioni, vedere Recordset: Dichiarazione di una classe per una tabella (ODBC).

Attenzione

Il nome della tabella sarà vuoto se il framework non è in grado di identificare un nome di tabella, se sono stati specificati più nomi di tabella o se non è stato possibile interpretare un'istruzione CALL . Quando si usa un'istruzione CALL , non inserire spazi vuoti tra la parentesi graffa e la CALL parola chiave , né prima della parentesi graffa o prima della parola chiave in un'istruzione SELECTSELECT .

`CRecordset::GetFieldValue`

Recupera i dati del campo nel record corrente.

void GetFieldValue(
    LPCTSTR lpszName,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringA& strValue
);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringW& strValue
);

void GetFieldValue(
    short nIndex,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    short nIndex,
    CStringA& strValue);

void GetFieldValue(
    short nIndex,
    CStringW& strValue);

Parametri

lpszName
Nome di un campo.

varValue Riferimento a un CDBVariant oggetto che archivierà il valore del campo.

nFieldType
Tipo di dati ODBC C del campo. Usando il valore predefinito, DEFAULT_FIELD_TYPE, forza GetFieldValue a determinare il tipo di dati C dal tipo di dati SQL, in base alla tabella seguente. In caso contrario, è possibile specificare direttamente il tipo di dati o scegliere un tipo di dati compatibile; Ad esempio, è possibile archiviare qualsiasi tipo di dati in SQL_C_CHAR.

Tipo di dati C	Tipo di dati SQL
`SQL_C_BIT`	`SQL_BIT`
`SQL_C_UTINYINT`	`SQL_TINYINT`
`SQL_C_SSHORT`	`SQL_SMALLINT`
`SQL_C_SLONG`	`SQL_INTEGER`
`SQL_C_FLOAT`	`SQL_REAL`
`SQL_C_DOUBLE`	`SQL_FLOATSQL_DOUBLE`
`SQL_C_TIMESTAMP`	`SQL_DATESQL_TIMESQL_TIMESTAMP`
`SQL_C_CHAR`	`SQL_NUMERICSQL_DECIMALSQL_BIGINTSQL_CHARSQL_VARCHARSQL_LONGVARCHAR`
`SQL_C_BINARY`	`SQL_BINARYSQL_VARBINARYSQL_LONGVARBINARY`

Per altre informazioni sui tipi di dati ODBC, vedere gli argomenti "Tipi di dati SQL" e "Tipi di dati C" nell'Appendice D di Windows SDK.

nIndex
Indice in base zero del campo.

strValue
Riferimento a un CString oggetto che archivierà il valore del campo convertito in testo, indipendentemente dal tipo di dati del campo.

Osservazioni:

È possibile cercare un campo in base al nome o all'indice. È possibile archiviare il valore del campo in un CDBVariant oggetto o in un CString oggetto .

Se è stato implementato il recupero delle righe bulk, il record corrente viene sempre posizionato sul primo record di un set di righe. Per utilizzare GetFieldValue in un record all'interno di un determinato set di righe, è prima necessario chiamare la SetRowsetCursorPosition funzione membro per spostare il cursore nella riga desiderata all'interno di tale set di righe. Quindi chiamare GetFieldValue per la riga. Per implementare il recupero delle righe bulk, è necessario specificare l'opzione CRecordset::useMultiRowFetch del dwOptions parametro nella Open funzione membro.

È possibile usare GetFieldValue per recuperare in modo dinamico i campi in fase di esecuzione anziché associarli staticamente in fase di progettazione. Ad esempio, se è stato dichiarato un oggetto recordset direttamente da CRecordset, è necessario usare GetFieldValue per recuperare i dati del campo, lo scambio di campi di record (RFX) o lo scambio di campi di record bulk (RFX bulk), non viene implementato.

Nota

Se si dichiara un oggetto recordset senza derivare da CRecordset, non è caricata la libreria di cursori ODBC. La libreria di cursori richiede che il recordset abbia almeno una colonna associata; Tuttavia, quando si usa CRecordset direttamente, nessuna delle colonne è associata. Le funzioni CDatabase::OpenEx membro e CDatabase::Open controllano se la libreria di cursori verrà caricata.

GetFieldValue chiama la funzione SQLGetDataAPI ODBC . Se il driver restituisce il valore SQL_NO_TOTAL per la lunghezza effettiva del valore del campo, GetFieldValue genera un'eccezione. Per altre informazioni su SQLGetData, vedere Windows SDK.

Esempio

Il codice di esempio seguente illustra le chiamate a GetFieldValue per un oggetto recordset dichiarato direttamente da CRecordset.

// Create and open a database object;
// do not load the cursor library
CDatabase db;
db.OpenEx(NULL, CDatabase::forceOdbcDialog);

// Create and open a recordset object
// directly from CRecordset. Note that a
// table must exist in a connected database.
// Use forwardOnly type recordset for best
// performance, since only MoveNext is required
CRecordset rs(&db);
rs.Open(CRecordset::forwardOnly, _T("SELECT * FROM Customer"));

// Create a CDBVariant object to
// store field data
CDBVariant varValue;

// Loop through the recordset,
// using GetFieldValue and
// GetODBCFieldCount to retrieve
// data in all columns
short nFields = rs.GetODBCFieldCount();
while (!rs.IsEOF())
{
   for (short index = 0; index < nFields; index++)
   {
      rs.GetFieldValue(index, varValue);
      // do something with varValue
   }
   rs.MoveNext();
}

rs.Close();
db.Close();

Nota

A differenza della classe CDaoRecordsetDAO , CRecordset non ha una SetFieldValue funzione membro. Se si crea un oggetto direttamente da CRecordset, è di sola lettura.

Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

`CRecordset::GetODBCFieldCount`

Recupera il numero totale di campi nell'oggetto recordset.

short GetODBCFieldCount() const;

Valore restituito

Numero di campi nel recordset.

Osservazioni:

Per altre informazioni sulla creazione di recordset, vedere Recordset: Creazione e chiusura di recordset (ODBC).

`CRecordset::GetODBCFieldInfo`

Ottiene informazioni sui campi nel recordset.

void GetODBCFieldInfo(
    LPCTSTR lpszName,
    CODBCFieldInfo& fieldinfo);

void GetODBCFieldInfo(
    short nIndex,
    CODBCFieldInfo& fieldinfo);

Parametri

lpszName
Nome di un campo.

fieldinfo
Riferimento a una CODBCFieldInfo struttura.

nIndex
Indice in base zero del campo.

Osservazioni:

Una versione della funzione consente di cercare un campo in base al nome. L'altra versione consente di cercare un campo per indice.

Per una descrizione delle informazioni restituite, vedere la CODBCFieldInfo struttura .

Per altre informazioni sulla creazione di recordset, vedere Recordset: Creazione e chiusura di recordset (ODBC).

`CRecordset::GetRecordCount`

Determina le dimensioni del recordset.

long GetRecordCount() const;

Valore restituito

Numero di record nel recordset; 0 se il recordset non contiene record; o -1 se il conteggio dei record non può essere determinato.

Osservazioni:

Attenzione

Il conteggio dei record viene mantenuto come "segno d'acqua elevato", il record con il numero più alto ancora visto quando l'utente passa attraverso i record. Il numero totale di record è noto solo dopo che l'utente è stato spostato oltre l'ultimo record. Per motivi di prestazioni, il conteggio non viene aggiornato quando si chiama MoveLast. Per contare manualmente i record, chiamare MoveNext ripetutamente fino a quando non restituisce un valore diverso da IsEOF zero. L'aggiunta di un record tramite CRecordset:AddNew e Update aumenta il conteggio. L'eliminazione di un record tramite CRecordset::Delete riduce il conteggio.

`CRecordset::GetRowsetSize`

Ottiene l'impostazione corrente per il numero di righe che si desidera recuperare durante un determinato recupero.

DWORD GetRowsetSize() const;

Valore restituito

Numero di righe da recuperare durante un determinato recupero.

Osservazioni:

Se si usa il recupero delle righe bulk, le dimensioni predefinite del set di righe quando il recordset viene aperto è 25; altrimenti, è 1.

Per implementare il recupero delle righe bulk, è necessario specificare l'opzione CRecordset::useMultiRowFetch nel dwOptions parametro della Open funzione membro. Per modificare l'impostazione per le dimensioni del set di righe, chiamare SetRowsetSize.

Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

`CRecordset::GetRowsFetched`

Determina il numero di record recuperati dopo un recupero.

DWORD GetRowsFetched() const;

Valore restituito

Numero di righe recuperate dall'origine dati dopo un determinato recupero.

Osservazioni:

Ciò è utile quando è stato implementato il recupero delle righe in blocco. Le dimensioni del set di righe indicano normalmente il numero di righe recuperate da un recupero. Tuttavia, il numero totale di righe nel recordset influisce anche sul numero di righe recuperate in un set di righe. Ad esempio, se il recordset ha 10 record con un'impostazione di dimensione del set di righe pari a quattro, il ciclo nel recordset chiamando MoveNext comporterà la presenza di solo due record nel set di righe finale.

Per implementare il recupero delle righe bulk, è necessario specificare l'opzione CRecordset::useMultiRowFetch nel parametro dwOptions della Open funzione membro. Per specificare le dimensioni del set di righe, chiamare SetRowsetSize.

Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

Esempio

CMultiCustomer rs(&m_dbCust);

// Set the rowset size
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// loop through the recordset by rowsets
while (!rs.IsEOF())
{
   for (int rowCount = 0; rowCount < (int)rs.GetRowsFetched(); rowCount++)
   {
      // do something
   }

   rs.MoveNext();
}

rs.Close();

`CRecordset::GetRowStatus`

Ottiene lo stato di una riga nel set di righe corrente.

WORD GetRowStatus(WORD wRow) const;

Parametri

wRow
Posizione in base unica di una riga nel set di righe corrente. Questo valore può variare da 1 alla dimensione del set di righe.

Valore restituito

Valore di stato per la riga. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

GetRowStatus restituisce un valore che indica qualsiasi modifica dello stato della riga dall'ultimo recupero dall'origine dati o che non è stata recuperata alcuna riga corrispondente a wRow . Nella tabella seguente sono elencati i valori restituiti possibili.

Valore di stato	Descrizione
`SQL_ROW_SUCCESS`	La riga è invariata.
`SQL_ROW_UPDATED`	La riga è stata aggiornata.
`SQL_ROW_DELETED`	La riga è stata eliminata.
`SQL_ROW_ADDED`	La riga è stata aggiunta.
`SQL_ROW_ERROR`	La riga non è verificabile a causa di un errore.
`SQL_ROW_NOROW`	Nessuna riga corrisponde a `wRow`.

Per altre informazioni, vedere la funzione SQLExtendedFetch API ODBC in Windows SDK.

`CRecordset::GetStatus`

Determina l'indice del record corrente nel recordset e se l'ultimo record è stato visualizzato.

void GetStatus(CRecordsetStatus& rStatus) const;

Parametri

rStatus
Riferimento a un oggetto CRecordsetStatus. Per altre informazioni, vedere Note.

Osservazioni:

CRecordset tenta di tenere traccia dell'indice, ma in alcune circostanze questo potrebbe non essere possibile. Vedere GetRecordCount per una spiegazione.

La CRecordsetStatus struttura ha il formato seguente:

struct CRecordsetStatus
{
    long m_lCurrentRecord;
    BOOL m_bRecordCountFinal;
};

I due membri di CRecordsetStatus hanno i significati seguenti:

m_lCurrentRecord Contiene l'indice in base zero del record corrente nel recordset, se noto. Se l'indice non può essere determinato, questo membro contiene AFX_CURRENT_RECORD_UNDEFINED (-2). Se IsBOF è TRUE (recordset vuoto o tentativo di scorrere prima del primo record), m_lCurrentRecord viene impostato su AFX_CURRENT_RECORD_BOF (-1). Se nel primo record, viene impostato su 0, secondo record 1 e così via.
m_bRecordCountFinal Diverso da zero se è stato determinato il numero totale di record nel recordset. In genere, questa operazione deve essere eseguita a partire dall'inizio del recordset e chiamando MoveNext fino a quando IsEOF non restituisce un valore diverso da zero. Se questo membro è zero, il conteggio dei record restituito da GetRecordCount, se non -1, è solo un conteggio "high water mark" dei record.

`CRecordset::GetSQL`

Chiamare questa funzione membro per ottenere l'istruzione SQL usata per selezionare i record del recordset all'apertura.

const CString& GetSQL() const;

Valore restituito

Riferimento const a un CString oggetto contenente l'istruzione SQL.

Osservazioni:

In genere si tratta di un'istruzione SQL SELECT . La stringa restituita da GetSQL è di sola lettura.

La stringa restituita da è in genere diversa da GetSQL qualsiasi stringa passata al recordset nel lpszSQL parametro alla Open funzione membro. Ciò è dovuto al fatto che il recordset costruisce un'istruzione SQL completa in base a ciò che è stato passato a Open, ciò che è stato specificato con ClassWizard, ciò che è possibile specificare nei m_strFilter membri dati e m_strSort e tutti i parametri specificati. Per informazioni dettagliate sul modo in cui il recordset costruisce questa istruzione SQL, vedere Recordset: How Recordsets Select Records (ODBC).

Nota

Chiamare questa funzione membro solo dopo aver chiamato Open.

`CRecordset::GetTableName`

Ottiene il nome della tabella SQL su cui è basata la query del recordset.

const CString& GetTableName() const;

Valore restituito

Riferimento const a un CString oggetto contenente il nome della tabella, se il recordset è basato su una tabella; in caso contrario, una stringa vuota.

Osservazioni:

GetTableName è valido solo se il recordset è basato su una tabella, non un join di più tabelle o una query predefinita (stored procedure). Il nome è di sola lettura.

Nota

Chiamare questa funzione membro solo dopo aver chiamato Open.

`CRecordset::IsBOF`

Restituisce un valore diverso da zero se il recordset è stato posizionato prima del primo record. Non esiste alcun record corrente.

BOOL IsBOF() const;

Valore restituito

Diverso da zero se il recordset non contiene record o se è stato eseguito lo scorrimento indietro prima del primo record; in caso contrario, 0.

Osservazioni:

Chiamare questa funzione membro prima di scorrere dal record al record per sapere se si è passati prima del primo record dell'oggetto recordset. È anche possibile utilizzare IsBOF insieme IsEOF a per determinare se il recordset contiene record o è vuoto. Immediatamente dopo la chiamata Opena , se il recordset non contiene record, IsBOF restituisce un valore diverso da zero. Quando si apre un recordset con almeno un record, il primo record è il record corrente e IsBOF restituisce 0.

Se il primo record è il record corrente e si chiama MovePrev, IsBOF restituirà un valore diverso da zero. Se IsBOF restituisce un valore diverso da zero e si chiama MovePrev, si verifica un errore. Se IsBOF restituisce un valore diverso da zero, il record corrente non è definito e qualsiasi azione che richiede un record corrente genererà un errore.

Esempio

Questo esempio usa IsBOF e IsEOF per rilevare i limiti di un recordset mentre il codice scorre il recordset in entrambe le direzioni.

// Open a recordset; first record is current
// Open a recordset; first record is current
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if(rsCustSet.IsBOF())
   return;
   // The recordset is empty

// Scroll to the end of the recordset, past
// the last record, so no record is current
while (!rsCustSet.IsEOF())
   rsCustSet.MoveNext();

// Move to the last record
rsCustSet.MoveLast();

// Scroll to beginning of the recordset, before
// the first record, so no record is current
while(!rsCustSet.IsBOF())
   rsCustSet.MovePrev();

// First record is current again
rsCustSet.MoveFirst();

`CRecordset::IsDeleted`

Determina se il record corrente è stato eliminato.

BOOL IsDeleted() const;

Valore restituito

Diverso da zero se il recordset è posizionato su un record eliminato; in caso contrario, 0.

Osservazioni:

Se si scorre fino a un record e IsDeleted restituisce TRUE (diverso da zero), è necessario scorrere fino a un altro record prima di poter eseguire qualsiasi altra operazione del recordset.

Il risultato di IsDeleted dipende da molti fattori, ad esempio il tipo di recordset, se il recordset è aggiornabile, se è stata specificata l'opzione all'apertura CRecordset::skipDeletedRecords del recordset, se i pacchetti driver hanno eliminato record e se sono presenti più utenti.

Per altre informazioni sulla CRecordset::skipDeletedRecords compressione dei driver e , vedere la funzione membro Open .

Nota

Se è stato implementato il recupero delle righe bulk, non è consigliabile chiamare IsDeleted. Chiamare invece la funzione membro GetRowStatus . Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

`CRecordset::IsEOF`

Restituisce un valore diverso da zero se il recordset è stato posizionato dopo l'ultimo record. Non esiste alcun record corrente.

BOOL IsEOF() const;

Valore restituito

Diverso da zero se il recordset non contiene record o se è stato eseguito lo scorrimento oltre l'ultimo record; in caso contrario, 0.

Osservazioni:

Chiamare questa funzione membro mentre si scorre dal record al record per sapere se si è superato l'ultimo record del recordset. È anche possibile utilizzare IsEOF per determinare se il recordset contiene record o è vuoto. Immediatamente dopo la chiamata Opena , se il recordset non contiene record, IsEOF restituisce un valore diverso da zero. Quando si apre un recordset con almeno un record, il primo record è il record corrente e IsEOF restituisce 0.

Se l'ultimo record è il record corrente quando si chiama MoveNext, IsEOF restituirà un valore diverso da zero. Se IsEOF restituisce un valore diverso da zero e si chiama MoveNext, si verifica un errore. Se IsEOF restituisce un valore diverso da zero, il record corrente non è definito e qualsiasi azione che richiede un record corrente genererà un errore.

Esempio

Vedere l'esempio per IsBOF.

`CRecordset::IsFieldDirty`

Determina se il membro dati del campo specificato è stato modificato dopo Edit o AddNew è stato chiamato.

BOOL IsFieldDirty(void* pv);

Parametri

pv
Puntatore al membro dati del campo di cui si desidera controllare lo stato oppure NULL determinare se uno dei campi è dirty.

Valore restituito

Diverso da zero se il membro dati del campo specificato è cambiato dopo la chiamata AddNew o Edit; in caso contrario, 0.

Osservazioni:

I dati in tutti i membri dati di campo dirty verranno trasferiti al record nell'origine dati quando il record corrente viene aggiornato da una chiamata alla Update funzione membro di CRecordset (dopo una chiamata a Edit o AddNew).

Nota

Questa funzione membro non è applicabile ai recordset che usano il recupero delle righe bulk. Se il recupero delle righe bulk è stato implementato, IsFieldDirty restituirà sempre FAL edizione Standard e genererà un'asserzione non riuscita. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

La chiamata IsFieldDirty reimposta gli effetti delle chiamate precedenti a SetFieldDirty perché lo stato dirty del campo viene rivalutato. AddNew Nel caso in cui il valore del campo corrente sia diverso dal valore pseudo null, lo stato del campo viene impostato su dirty. Edit Nel caso in cui il valore del campo sia diverso dal valore memorizzato nella cache, lo stato del campo viene impostato su dirty.

IsFieldDirty viene implementato tramite DoFieldExchange.

Per altre informazioni sul flag dirty, vedere Recordset: How Recordsets Select Records (ODBC).

`CRecordset::IsFieldNull`

Restituisce un valore diverso da zero se il campo specificato nel record corrente è Null (non ha alcun valore).

BOOL IsFieldNull(void* pv);

Parametri

pv
Puntatore al membro dati del campo di cui si desidera controllare lo stato oppure NULL determinare se uno dei campi è Null.

Valore restituito

Diverso da zero se il membro dati del campo specificato è contrassegnato come Null; in caso contrario, 0.

Osservazioni:

Chiamare questa funzione membro per determinare se il membro dati del campo specificato di un recordset è stato contrassegnato come Null. Nella terminologia del database Null significa "senza valore" e non è uguale NULL a in C++. Se un membro dati di campo è contrassegnato come Null, viene interpretato come una colonna del record corrente per cui non è presente alcun valore.

Nota

Questa funzione membro non è applicabile ai recordset che usano il recupero delle righe bulk. Se è stato implementato il recupero delle righe bulk, verrà IsFieldNull restituito sempre FALSE e verrà restituita un'asserzione non riuscita. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

IsFieldNull viene implementato tramite DoFieldExchange.

`CRecordset::IsFieldNullable`

Restituisce un valore diverso da zero se il campo specificato nel record corrente può essere impostato su Null (senza valore).

BOOL IsFieldNullable(void* pv);

Parametri

pv
Puntatore al membro dati del campo di cui si desidera controllare lo stato oppure NULL determinare se uno dei campi può essere impostato su un valore Null.

Osservazioni:

Chiamare questa funzione membro per determinare se il membro dati del campo specificato è "nullable" (può essere impostato su un valore Null; C++ NULL non è uguale a Null, che, nella terminologia del database, significa "senza valore".

Nota

Se è stato implementato il recupero delle righe bulk, non è possibile chiamare IsFieldNullable. Chiamare invece la GetODBCFieldInfo funzione membro per determinare se un campo può essere impostato su un valore Null. È sempre possibile chiamare GetODBCFieldInfo, indipendentemente dal fatto che sia stato implementato il recupero delle righe in blocco. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

Un campo che non può essere Null deve avere un valore. Se si tenta di impostare un campo di questo tipo su Null durante l'aggiunta o l'aggiornamento di un record, l'origine dati rifiuta l'aggiunta o l'aggiornamento e Update genererà un'eccezione. L'eccezione si verifica quando si chiama Update, non quando si chiama SetFieldNull.

Se si usa NULL per il primo argomento della funzione, la funzione verrà applicata solo ai campi, non param ai outputColumn campi. Ad esempio, la chiamata

SetFieldNull(NULL);

imposta solo outputColumn i campi su NULL. param I campi non saranno interessati.

Per lavorare sui param campi, è necessario specificare l'indirizzo effettivo dell'utente param su cui si vuole lavorare, ad esempio:

SetFieldNull(&m_strParam);

Ciò significa che non è possibile impostare tutti i param campi su NULL, come è possibile con i outputColumn campi.

IsFieldNullable viene implementato tramite DoFieldExchange.

`CRecordset::IsOpen`

Determina se il recordset è già aperto.

BOOL IsOpen() const;

Valore restituito

Diverso da zero se la funzione membro o Requery dell'oggetto Open recordset è stata chiamata in precedenza e il recordset non è stato chiuso; in caso contrario, 0.

`CRecordset::m_hstmt`

Contiene un handle per la struttura dei dati dell'istruzione ODBC, di tipo HSTMT, associato al recordset.

Osservazioni:

Ogni query in un'origine dati ODBC è associata a un oggetto HSTMT.

Attenzione

Non usare m_hstmt prima Open di essere stato chiamato.

In genere non è necessario accedere HSTMT direttamente a , ma potrebbe essere necessario per l'esecuzione diretta delle istruzioni SQL. La ExecuteSQL funzione membro della classe CDatabase fornisce un esempio di utilizzo m_hstmtdi .

`CRecordset::m_nFields`

Contiene il numero di membri dati del campo nella classe recordset; ovvero il numero di colonne selezionate dal recordset dall'origine dati.

Osservazioni:

Il costruttore per la classe recordset deve essere inizializzato m_nFields con il numero corretto. Se non è stato implementato il recupero delle righe bulk, ClassWizard scrive automaticamente questa inizializzazione quando viene usata per dichiarare la classe recordset. È anche possibile scriverlo manualmente.

Il framework usa questo numero per gestire l'interazione tra i membri dati del campo e le colonne corrispondenti del record corrente nell'origine dati.

Attenzione

Questo numero deve corrispondere al numero di "colonne di output" registrate in DoFieldExchange o DoBulkFieldExchange dopo una chiamata a SetFieldType con il parametro CFieldExchange::outputColumn.

È possibile associare le colonne in modo dinamico, come illustrato nell'articolo "Recordset: Associazione dinamica di colonne di dati". In questo caso, è necessario aumentare il conteggio in m_nFields per riflettere il numero di chiamate di funzione RFX o RFX bulk nella DoFieldExchange funzione membro o DoBulkFieldExchange per le colonne associate dinamicamente.

Per altre informazioni, vedere gli articoli Recordset: Binding dinamico di colonne di dati (ODBC) e Recordset: recupero di record in blocco (ODBC).For more information, see the articles Recordset: Dynamically Binding Data Columns (ODBC) and Recordset: Fetching Records in Bulk (ODBC).

Esempio

vedere Scambio di campi di record: uso di RFX.

`CRecordset::m_nParams`

Contiene il numero di membri dati dei parametri nella classe recordset; ovvero il numero di parametri passati con la query del recordset.

Osservazioni:

Se la classe recordset include membri dati di parametro, il costruttore per la classe deve inizializzare m_nParams con il numero corretto. Il valore m_nParams predefinito è 0. Se si aggiungono membri dati dei parametri (che è necessario eseguire manualmente) è necessario aggiungere manualmente anche un'inizializzazione nel costruttore della classe per riflettere il numero di parametri (che devono essere almeno grandi del numero di segnaposto '' nella m_strFilter stringa o m_strSort ).

Il framework usa questo numero quando parametrizza la query del recordset.

Attenzione

Questo numero deve corrispondere al numero di "params" registrati in DoFieldExchange o DoBulkFieldExchange dopo una chiamata a SetFieldType con un valore di parametro , CFieldExchange::inputParamCFieldExchange::param, CFieldExchange::outputParamo CFieldExchange::inoutParam.

Esempio

Vedere gli articoli Recordset: Parametrizzazione di un oggetto Recordset (ODBC) e Scambio di campi di record: uso di RFX.

`CRecordset::m_pDatabase`

Contiene un puntatore all'oggetto tramite il quale il recordset è connesso a un'origine CDatabase dati.

Osservazioni:

Questa variabile viene impostata in due modi. In genere, si passa un puntatore a un oggetto già connesso CDatabase quando si costruisce l'oggetto recordset. Se si passa NULL invece, CRecordset crea un CDatabase oggetto per l'utente e lo connette. In entrambi i casi, CRecordset archivia il puntatore in questa variabile.

In genere non è necessario usare direttamente il puntatore archiviato in m_pDatabase. Se si scrivono estensioni personalizzate in CRecordset, tuttavia, potrebbe essere necessario usare il puntatore. Ad esempio, potrebbe essere necessario il puntatore se si generano oggetti personalizzati CDBException. Oppure potrebbe essere necessario se è necessario eseguire un'operazione usando lo stesso CDatabase oggetto, ad esempio l'esecuzione di transazioni, l'impostazione dei timeout o la chiamata diretta della ExecuteSQL funzione membro della classe CDatabase per eseguire istruzioni SQL.

`CRecordset::m_strFilter`

Dopo aver costruito l'oggetto recordset, ma prima di chiamare la Open relativa funzione membro, utilizzare questo membro dati per archiviare un CString oggetto contenente una clausola SQL WHERE .

Osservazioni:

Il recordset usa questa stringa per vincolare (o filtrare) i record selezionati durante la Open chiamata o Requery . Ciò è utile per la selezione di un subset di record, ad esempio "tutti i venditori basati in California" ("state = CA"). La sintassi ODBC SQL per una WHERE clausola è

WHERE search-condition

Non includere la WHERE parola chiave nella stringa. Il framework lo fornisce.

È anche possibile parametrizzare la stringa di filtro inserendo al suo interno segnaposto '', dichiarando un membro dati di parametro nella classe per ogni segnaposto e passando parametri al recordset in fase di esecuzione. In questo modo è possibile costruire il filtro in fase di esecuzione. Per altre informazioni, vedere Recordset: Parametrizzazione di un oggetto Recordset (ODBC).For more information, see Recordset: Parameterizing a Recordset (ODBC).

Per altre informazioni sulle clausole SQL WHERE , vedere SQL. Per altre informazioni sulla selezione e il filtro dei record, vedere Recordset: Filtering Records (ODBC).

Esempio

CCustomer rsCustSet(&m_dbCust);

// Set the filter
rsCustSet.m_strFilter = _T("L_Name = 'Flanders'");

// Run the filtered query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

`CRecordset::m_strSort`

Osservazioni:

Il recordset usa questa stringa per ordinare i record selezionati durante la Open chiamata o Requery . È possibile usare questa funzionalità per ordinare un recordset in una o più colonne. La sintassi SQL ODBC per una ORDER BY clausola è

ORDER BY sort-specification [, sort-specification]...

dove una specifica di ordinamento è un numero intero o un nome di colonna. È anche possibile specificare l'ordine crescente o decrescente (l'ordine è crescente per impostazione predefinita) aggiungendo "ASC" o "DESC" all'elenco di colonne nella stringa di ordinamento. I record selezionati vengono ordinati prima in base alla prima colonna elencata, quindi al secondo e così via. Ad esempio, è possibile ordinare un recordset "Customers" in base al cognome, quindi al nome. Il numero di colonne che è possibile elencare dipende dall'origine dati. Per altre informazioni, vedere Windows SDK.

Non includere la ORDER BY parola chiave nella stringa. Il framework lo fornisce.

Per altre informazioni sulle clausole SQL, vedere SQL. Per altre informazioni sull'ordinamento dei record, vedere Recordset: Ordinamento di record (ODBC).For more information about sorting records, see Recordset: Sorting Records (ODBC).

Esempio

CCustomer rsCustSet(&m_dbCust);

// Set the sort string
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");

// Run the sorted query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

`CRecordset::Move`

Sposta il puntatore del record corrente all'interno del recordset, in avanti o indietro.

virtual void Move(
    long nRows,
    WORD wFetchType = SQL_FETCH_RELATIVE);

Parametri

nRows
Numero di righe da spostare avanti o indietro. I valori positivi si spostano in avanti, verso la fine del recordset. I valori negativi si spostano all'indietro, verso l'inizio.

wFetchType
Determina il set di righe che Move verrà recuperato. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

Se si passa un valore pari a 0 per nRows, Move aggiorna il record corrente; Move terminerà qualsiasi modalità o Edit corrente AddNew e ripristinerà il valore del record corrente prima AddNew o Edit è stato chiamato.

Nota

Quando si passa attraverso un recordset, non è possibile ignorare i record eliminati. Per altre informazioni, vedere CRecordset::IsDeleted. Quando si apre un CRecordset oggetto con il skipDeletedRecords set di opzioni, Move asserisce se il nRows parametro è 0. Questo comportamento impedisce l'aggiornamento delle righe eliminate da altre applicazioni client che usano gli stessi dati. Per una descrizione di skipDeletedRecords, vedere il dwOption parametro in Open .

Move riposiziona il recordset in base ai set di righe. In base ai valori per nRows e wFetchType, Move recupera il set di righe appropriato e quindi rende il primo record in tale set di righe il record corrente. Se non è stato implementato il recupero delle righe bulk, le dimensioni del set di righe sono sempre 1. Quando si recupera un set di righe, Move chiama direttamente la CheckRowsetError funzione membro per gestire eventuali errori risultanti dal recupero.

A seconda dei valori passati, Move equivale ad altre CRecordset funzioni membro. In particolare, il valore di wFetchType può indicare una funzione membro più intuitiva e spesso il metodo preferito per lo spostamento del record corrente.

Nella tabella seguente sono elencati i valori possibili per wFetchType, il set di righe che Move recupererà in base a wFetchType e nRowse qualsiasi funzione membro equivalente corrispondente a wFetchType.

Wfetchtype	Set di righe recuperato	Funzione membro equivalente
`SQL_FETCH_RELATIVE` (valore predefinito)	Set di righe che inizia `nRows` le righe dalla prima riga del set di righe corrente.
`SQL_FETCH_NEXT`	Set di righe successivo; `nRows` viene ignorato.	`MoveNext`
`SQL_FETCH_PRIOR`	Set di righe precedente; `nRows` viene ignorato.	`MovePrev`
`SQL_FETCH_FIRST`	Primo set di righe nel recordset; `nRows` viene ignorato.	`MoveFirst`
`SQL_FETCH_LAST`	Ultimo set di righe completo nel recordset; `nRows` viene ignorato.	`MoveLast`
`SQL_FETCH_ABSOLUTE`	Se `nRows`> 0, il set di righe che inizia `nRows` le righe dall'inizio del recordset. Se `nRows`< 0, il set di righe che inizia `nRows` le righe dalla fine del recordset. Se `nRows` = 0, viene restituita una condizione di inizio file (BOF).	`SetAbsolutePosition`
`SQL_FETCH_BOOKMARK`	Set di righe a partire dalla riga il cui valore del segnalibro corrisponde a `nRows`.	`SetBookmark`

Nota

Per i recordset forward-only, Move è valido solo con il valore per wFetchTypeSQL_FETCH_NEXT .

Attenzione

La chiamata Move genera un'eccezione se il recordset non dispone di record. Per determinare se il recordset contiene record, chiamare IsBOF e IsEOF.

Nota

Se è stato eseguito lo scorrimento oltre l'inizio o la fine del recordset (IsBOF o IsEOF restituisce un valore diverso da zero), la chiamata a una Move funzione genererà un'eccezione CDBException. Ad esempio, se IsEOF restituisce un valore diverso da zero e IsBOF non lo fa, genererà MoveNext un'eccezione, ma MovePrev non lo farà.

Nota

Se si chiama Move durante l'aggiornamento o l'aggiunta del record corrente, gli aggiornamenti vengono persi senza avvisi.

Per altre informazioni sulla navigazione dei recordset, vedere gli articoli Recordset: Scorrimento (ODBC) e Recordset: Segnalibri e posizioni assolute (ODBC). Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC). Per informazioni correlate, vedere la funzione SQLExtendedFetch API ODBC in Windows SDK.

Esempio

// rs is a CRecordset or a CRecordset-derived object

// Change the rowset size to 5
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// Move to the first record in the recordset
rs.MoveFirst();

// Move to the sixth record
rs.Move(5);
// Other equivalent ways to move to the sixth record:
rs.Move(6, SQL_FETCH_ABSOLUTE);
rs.SetAbsolutePosition(6);
// In this case, the sixth record is the first record in the next rowset,
// so the following are also equivalent:
rs.MoveFirst();
rs.Move(1, SQL_FETCH_NEXT);

rs.MoveFirst();
rs.MoveNext();

`CRecordset::MoveFirst`

Rende il primo record nel primo set di righe il record corrente.

void MoveFirst();

Osservazioni:

Indipendentemente dal fatto che il recupero delle righe bulk sia stato implementato, questo sarà sempre il primo record nel recordset.

Non è necessario chiamare MoveFirst immediatamente dopo aver aperto il recordset. In quel momento, il primo record (se presente) è automaticamente il record corrente.

Nota

Questa funzione membro non è valida per i recordset forward-only.

Nota

Quando si passa attraverso un recordset, non è possibile ignorare i record eliminati. Per informazioni dettagliate, vedere la IsDeleted funzione membro.

Attenzione

La chiamata a una delle Move funzioni genera un'eccezione se il recordset non contiene record. Per determinare se il recordset contiene record, chiamare IsBOF e IsEOF.

Nota

Se si chiama una delle Move funzioni durante l'aggiornamento o l'aggiunta del record corrente, gli aggiornamenti vengono persi senza avvisi.

Esempio

Vedere l'esempio per IsBOF.

`CRecordset::MoveLast`

Rende il primo record nell'ultimo set di righe completo il record corrente.

void MoveLast();

Osservazioni:

Se non è stato implementato il recupero delle righe bulk, il recordset ha una dimensione del set di righe pari a 1, quindi MoveLast passa all'ultimo record nel recordset.

Nota

Questa funzione membro non è valida per i recordset forward-only.

Nota

Quando si passa attraverso un recordset, non è possibile ignorare i record eliminati. Per informazioni dettagliate, vedere la IsDeleted funzione membro.

Attenzione

La chiamata a una delle Move funzioni genera un'eccezione se il recordset non contiene record. Per determinare se il recordset contiene record, chiamare IsBOF e IsEOF.

Nota

Se si chiama una delle Move funzioni durante l'aggiornamento o l'aggiunta del record corrente, gli aggiornamenti vengono persi senza avvisi.

Esempio

Vedere l'esempio per IsBOF.

`CRecordset::MoveNext`

Rende il primo record nel set di righe successivo il record corrente.

void MoveNext();

Osservazioni:

Se non è stato implementato il recupero delle righe bulk, il recordset ha una dimensione del set di righe pari a 1, quindi MoveNext passa al record successivo.

Nota

Quando si passa attraverso un recordset, non è possibile ignorare i record eliminati. Per informazioni dettagliate, vedere la IsDeleted funzione membro.

Attenzione

La chiamata a una delle Move funzioni genera un'eccezione se il recordset non contiene record. Per determinare se il recordset contiene record, chiamare IsBOF e IsEOF.

Nota

È anche consigliabile chiamare prima di chiamare IsEOFMoveNext. Ad esempio, se è stato eseguito lo scorrimento oltre la fine del recordset, IsEOF restituirà un valore diverso da zero. Una chiamata successiva a MoveNext genererà un'eccezione.

Nota

Se si chiama una delle Move funzioni durante l'aggiornamento o l'aggiunta del record corrente, gli aggiornamenti vengono persi senza avvisi.

Esempio

Vedere l'esempio per IsBOF.

`CRecordset::MovePrev`

Rende il primo record nel set di righe precedente il record corrente.

void MovePrev();

Osservazioni:

Se non è stato implementato il recupero delle righe bulk, il recordset ha una dimensione del set di righe pari a 1, quindi MovePrev passa al record precedente.

Nota

Questa funzione membro non è valida per i recordset forward-only.

Nota

Quando si passa attraverso un recordset, non è possibile ignorare i record eliminati. Per informazioni dettagliate, vedere la IsDeleted funzione membro.

Attenzione

La chiamata a una delle Move funzioni genera un'eccezione se il recordset non contiene record. Per determinare se il recordset contiene record, chiamare IsBOF e IsEOF.

Nota

È anche consigliabile chiamare prima di chiamare IsBOFMovePrev. Ad esempio, se è stato eseguito lo scorrimento prima dell'inizio del recordset, IsBOF restituirà un valore diverso da zero. Una chiamata successiva a MovePrev genererà un'eccezione.

Nota

Se si chiama una delle Move funzioni durante l'aggiornamento o l'aggiunta del record corrente, gli aggiornamenti vengono persi senza avvisi.

Esempio

Vedere l'esempio per IsBOF.

`CRecordset::OnSetOptions`

Chiamato per impostare le opzioni (utilizzate nella selezione) per l'istruzione ODBC specificata.

virtual void OnSetOptions(HSTMT hstmt);

Parametri

hstmt
Oggetto HSTMT dell'istruzione ODBC le cui opzioni devono essere impostate.

Osservazioni:

Chiamare OnSetOptions per impostare le opzioni (utilizzate nella selezione) per l'istruzione ODBC specificata. Il framework chiama questa funzione membro per impostare le opzioni iniziali per il recordset. OnSetOptions determina il supporto dell'origine dati per i cursori scorrevoli e per la concorrenza del cursore e imposta le opzioni del recordset di conseguenza. (Mentre OnSetOptions viene usato per le operazioni di selezione, OnSetUpdateOptions viene usato per le operazioni di aggiornamento).

Eseguire l'override OnSetOptions per impostare opzioni specifiche per il driver o l'origine dati. Ad esempio, se l'origine dati supporta l'apertura per l'accesso esclusivo, è possibile eseguire l'override OnSetOptions per sfruttare tale capacità.

Per altre informazioni sui cursori, vedere ODBC.

`CRecordset::OnSetUpdateOptions`

Chiamato per impostare le opzioni (utilizzate per l'aggiornamento) per l'istruzione ODBC specificata.

virtual void OnSetUpdateOptions(HSTMT hstmt);

Parametri

hstmt
Oggetto HSTMT dell'istruzione ODBC le cui opzioni devono essere impostate.

Osservazioni:

Chiamare OnSetUpdateOptions per impostare le opzioni (usate per l'aggiornamento) per l'istruzione ODBC specificata. Il framework chiama questa funzione membro dopo aver creato un HSTMT oggetto per aggiornare i record in un recordset. OnSetOptions Mentre viene usato per le operazioni di selezione, OnSetUpdateOptions viene usato per le operazioni di aggiornamento. OnSetUpdateOptions Determina il supporto dell'origine dati per i cursori scorrevoli e per la concorrenza del cursore e imposta di conseguenza le opzioni del recordset.

Eseguire l'override OnSetUpdateOptions per impostare le opzioni di un'istruzione ODBC prima che tale istruzione venga utilizzata per accedere a un database.

Per altre informazioni sui cursori, vedere ODBC.

`CRecordset::Open`

Apre il recordset recuperando la tabella o eseguendo la query rappresentata dal recordset.

virtual BOOL Open(
    UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE,
    LPCTSTR lpszSQL = NULL,
    DWORD dwOptions = none);

Parametri

nOpenType
Accettare il valore predefinito, AFX_DB_USE_DEFAULT_TYPEo usare uno dei valori seguenti di enum OpenType:

CRecordset::dynaset Recordset con scorrimento bidirezionale. L'apertura del recordset determina l'appartenenza e l'ordinamento dei record, ma le modifiche apportate da altri utenti ai valori dei dati sono visibili dopo un'operazione di recupero. I dynaset sono noti anche come recordset basati su keyset.
CRecordset::snapshot Recordset statico con scorrimento bidirezionale. L'apertura del recordset determina l'appartenenza e l'ordinamento dei record. Il recupero di un record determina i valori dei dati. Le modifiche apportate da altri utenti non sono visibili finché il recordset non viene chiuso e quindi riaperto.
CRecordset::dynamic Recordset con scorrimento bidirezionale. Le modifiche apportate da altri utenti all'appartenenza, all'ordine e ai valori dei dati sono visibili dopo un'operazione di recupero. Molti driver ODBC non supportano questo tipo di recordset.
CRecordset::forwardOnly Recordset di sola lettura con scorrimento in avanti.

Per CRecordset, il valore predefinito è CRecordset::snapshot. Il meccanismo di valore predefinito consente l'interazione tra le procedure guidate di Visual C++ e CRecordset di ODBC e CDaoRecordset di DAO le cui impostazione predefinite sono diverse.

Per altre informazioni su questi tipi di recordset, vedere Recordset (ODBC). Per informazioni correlate, vedere "Uso di cursori blocca e scorrevoli" in Windows SDK.

Attenzione

Se il tipo richiesto non è supportato, il framework genera un'eccezione.

lpszSQL
Puntatore di stringa contenente uno degli elementi seguenti:

Puntatore NULL .
Nome di una tabella.
Un'istruzione SQL SELECT (facoltativamente con una clausola SQL WHERE o ORDER BY ).
Istruzione CALL che specifica il nome di una query predefinita (stored procedure). Prestare attenzione a non inserire spazi vuoti tra la parentesi graffa e la CALL parola chiave .

Per altre informazioni su questa stringa, vedere la tabella e la discussione sul ruolo di ClassWizard nella sezione Osservazioni .

Nota

L'ordine delle colonne nel set di risultati deve corrispondere all'ordine delle chiamate di funzione RFX o RFX bulk nell'override DoFieldExchange della funzione o DoBulkFieldExchange .

dwOptions
Maschera di bit, che può specificare una combinazione dei valori elencati di seguito. Alcuni di questi si escludono a vicenda. Il valore predefinito è none.

CRecordset::none Nessun set di opzioni. Il valore di questo parametro e tutti gli altri valori si escludono a vicenda. Per impostazione predefinita, il recordset può essere aggiornato con Edit o Delete e consente l'aggiunta di nuovi record con AddNew. L'updatabilità dipende dall'origine dati e dall'opzione nOpenType specificata. L'ottimizzazione per le aggiunte in blocco non è disponibile. Il recupero delle righe in blocco non verrà implementato. I record eliminati non verranno ignorati durante la navigazione del recordset. I segnalibri non sono disponibili. Il controllo automatico dei campi modificati automatico è implementato.
CRecordset::appendOnly Non consentire Edit o Delete sul recordset. Consente solo AddNew. Questa opzione e CRecordset::readOnly si escludono a vicenda.
CRecordset::readOnly Aprire il recordset come di sola lettura. Questa opzione e CRecordset::appendOnly si escludono a vicenda.
CRecordset::optimizeBulkAdd Usare un'istruzione SQL preparata per ottimizzare l'aggiunta di più record contemporaneamente. Si applica solo se non si usa la funzione SQLSetPos API ODBC per aggiornare il recordset. Tramite il primo aggiornamento viene determinato quali campi vengono contrassegnati come modificati. Questa opzione e CRecordset::useMultiRowFetch si escludono a vicenda.
CRecordset::useMultiRowFetch Implementare il recupero delle righe bulk per consentire il recupero di più righe in una singola operazione di recupero. Si tratta di una funzionalità avanzata progettata per migliorare le prestazioni; Tuttavia, lo scambio di campi dei record in blocco non è supportato da ClassWizard. Questa opzione e CRecordset::optimizeBulkAdd si escludono a vicenda. Se si specifica CRecordset::useMultiRowFetch, l'opzione verrà attivata automaticamente (il doppio buffering non sarà disponibile); nei recordset forward-only l'opzione CRecordset::noDirtyFieldCheckCRecordset::useExtendedFetch verrà attivata automaticamente. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).
CRecordset::skipDeletedRecords Ignorare tutti i record eliminati durante lo spostamento all'interno del recordset. Ciò comporterà il rallentamento delle prestazioni in alcuni recuperi relativi. Questa opzione non è valida nei recordset forward-only. Se si chiama Move con il parametro nRows impostato su 0 e il CRecordset::skipDeletedRecords set di opzioni, Move asserirà . CRecordset::skipDeletedRecords è simile alla compressione del driver, il che significa che le righe eliminate vengono rimosse dal recordset. Tuttavia, se il driver contiene record, salterà solo i record eliminati; non ignorerà i record eliminati da altri utenti mentre il recordset è aperto. CRecordset::skipDeletedRecords ignorerà le righe eliminate da altri utenti.
CRecordset::useBookmarks Può utilizzare segnalibri nel recordset, se supportato. Con i segnalibri il recupero dei dati risulta rallentato, ma le prestazioni relative alla navigazione tra i dati migliorano. Non valido per i recordset forward-only. Per altre informazioni, vedere Recordset: Segnalibri e posizioni assolute (ODBC).
CRecordset::noDirtyFieldCheck Disattivare il controllo automatico dei campi dirty (doppio buffering). Ciò migliorerà le prestazioni; Tuttavia, è necessario contrassegnare manualmente i campi come dirty chiamando le SetFieldDirty funzioni membro e SetFieldNull . Il buffer doppio nella classe CRecordset è simile al doppio buffering nella classe CDaoRecordset. In , tuttavia, CRecordsetnon è possibile abilitare il doppio buffer nei singoli campi. È possibile abilitarlo per tutti i campi o disabilitarlo per tutti i campi. Se si specifica l'opzione , CRecordset::noDirtyFieldCheck l'opzione CRecordset::useMultiRowFetchviene attivata automaticamente, SetFieldNull ma SetFieldDirty non può essere usata nei recordset che implementano il recupero delle righe bulk.
CRecordset::executeDirect Non usare un'istruzione SQL preparata. Per migliorare le prestazioni, specificare questa opzione se la Requery funzione membro non verrà mai chiamata.
CRecordset::useExtendedFetch Implementare SQLExtendedFetch anziché SQLFetch. Questa condizione è progettata per implementare il recupero di righe di massa nei recordset forward-only. Se si specifica l'opzione in un recordset forward-only, CRecordset::useExtendedFetch l'opzione CRecordset::useMultiRowFetch verrà attivata automaticamente.
CRecordset::userAllocMultiRowBuffers L'utente allocherà i buffer di archiviazione per i dati. Usare questa opzione con CRecordset::useMultiRowFetch se si vuole allocare una risorsa di archiviazione personalizzata. In caso contrario, il framework allocherà automaticamente la risorsa di archiviazione necessaria. Per altre informazioni, vedere Recordset: recupero di record in blocco (ODBC). Specificando senza specificare CRecordset::userAllocMultiRowBuffersCRecordset::useMultiRowFetch i risultati in un'asserzione non riuscita.

Valore restituito

Diverso da zero se l'oggetto CRecordset è stato aperto correttamente; in caso contrario, 0 se CDatabase::Open viene chiamato restituisce 0.

Osservazioni:

È necessario chiamare questa funzione membro per eseguire la query definita dal recordset. Prima di chiamare Open, è necessario costruire l'oggetto recordset.

La connessione di questo recordset all'origine dati dipende dalla modalità di costruzione del recordset prima di chiamare Open. Se si passa un CDatabase oggetto al costruttore del recordset che non è stato connesso all'origine dati, questa funzione membro usa GetDefaultConnect per tentare di aprire l'oggetto di database. Se si passa NULL al costruttore del recordset, il costruttore costruisce un CDatabase oggetto per l'utente e Open tenta di connettere l'oggetto di database. Per informazioni dettagliate sulla chiusura del recordset e della connessione in queste circostanze diverse, vedere Close.

Nota

L'accesso a un'origine dati tramite un oggetto CRecordset è sempre condiviso. A differenza della CDaoRecordset classe, non è possibile usare un oggetto per aprire un'origine CRecordset dati con accesso esclusivo.

Quando si chiama Open, una query, in genere un'istruzione SQL SELECT , seleziona i record in base ai criteri illustrati nella tabella seguente.

Valore del parametro `lpszSQL`	I record selezionati sono determinati da	Esempio
`NULL`	Stringa restituita da `GetDefaultSQL`.
Nome tabella SQL	Tutte le colonne dell'elenco tabelle in `DoFieldExchange` o `DoBulkFieldExchange`.	`"Customer"`
Nome predefinito della query (stored procedure)	Colonne che devono essere restituite dalla query.	`"{call OverDueAccts}"`
`SELECT`column-list table-list `FROM`	Colonne specificate delle tabelle specificate.	`"SELECT CustId, CustName FROM` `Customer"`

Attenzione

Non inserire spazi vuoti aggiuntivi nella stringa SQL. Ad esempio, se si inseriscono spazi vuoti tra la parentesi graffa e la CALL parola chiave , MFC interpreta erroneamente la stringa SQL come nome di tabella e la incorpora in un'istruzione SELECT , che comporterà la generazione di un'eccezione. Analogamente, se la query predefinita usa un parametro di output, non inserire spazi vuoti tra la parentesi graffa e il simbolo ''. Infine, non è necessario inserire spazi vuoti prima della parentesi graffa in un'istruzione CALL o prima della parola chiave in un'istruzione SELECTSELECT .

La procedura consueta consiste nel passare NULL a Open. In questo caso, Open chiama GetDefaultSQL. Se si usa una classe derivata CRecordset , GetDefaultSQL specifica i nomi della tabella specificati in ClassWizard. Nel parametro lpszSQL è invece possibile specificare altre informazioni.

Indipendentemente dal passaggio, Open costruisce una stringa SQL finale per la query (la stringa può avere sql WHERE e ORDER BY clausole aggiunte alla lpszSQL stringa passata) e quindi esegue la query. È possibile esaminare la stringa costruita chiamando dopo aver chiamato GetSQLOpen. Per altre informazioni sul modo in cui il recordset costruisce un'istruzione SQL e seleziona i record, vedere Recordset: How Recordsets Select Records (ODBC).

I membri dei dati di campo della classe recordset sono associati alle colonne dei dati selezionati. Se vengono restituiti record, il primo di essi diventa il record corrente.

Se si desidera impostare le opzioni per il recordset, ad esempio un filtro o un ordinamento, specificarli dopo aver costruito l'oggetto recordset, ma prima di chiamare Open. Se si desidera aggiornare i record nel recordset dopo che il recordset è già aperto, chiamare Requery.

Per altre informazioni, inclusi altri esempi, vedere Recordset (ODBC), Recordset: How Recordsets Select Records (ODBC), and Recordset: Creating and Closing Recordsets (ODBC).

Esempio

Negli esempi di codice seguenti vengono illustrate diverse forme della Open chiamata.

// rsSnap, rsLName, and rsDefault are CRecordset or CRecordset-derived 
// objects

// Open rs using the default SQL statement, implement bookmarks, and turn 
// off automatic dirty field checking
rsSnap.Open(CRecordset::snapshot, NULL, CRecordset::useBookmarks |
   CRecordset::noDirtyFieldCheck);

// Pass a complete SELECT statement and open as a dynaset
rsLName.Open(CRecordset::dynaset, _T("Select L_Name from Customer"));

// Accept all defaults
rsDefault.Open();

`CRecordset::RefreshRowset`

Aggiornamenti i dati e lo stato di una riga nel set di righe corrente.

void RefreshRowset(
    WORD wRow,
    WORD wLockType = SQL_LOCK_NO_CHANGE);

Parametri

wRow
Posizione in base unica di una riga nel set di righe corrente. Questo valore può variare da zero alla dimensione del set di righe.

wLockType
Valore che indica come bloccare la riga dopo l'aggiornamento. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

Se si passa un valore pari a zero per wRow, ogni riga del set di righe verrà aggiornata.

Per usare RefreshRowset, è necessario aver implementato il recupero delle righe bulk specificando l'opzione CRecordset::useMulitRowFetch nella Open funzione membro.

RefreshRowset chiama la funzione SQLSetPosAPI ODBC . Il wLockType parametro specifica lo stato di blocco della riga dopo SQLSetPos l'esecuzione. Nella tabella seguente vengono descritti i valori possibili per wLockType.

wLockType	Descrizione
`SQL_LOCK_NO_CHANGE` (valore predefinito)	Il driver o l'origine dati garantisce che la riga si trova nello stesso stato bloccato o sbloccato precedentemente `RefreshRowset` chiamato.
`SQL_LOCK_EXCLUSIVE`	Il driver o l'origine dati blocca la riga esclusivamente. Non tutte le origini dati supportano questo tipo di blocco.
`SQL_LOCK_UNLOCK`	Il driver o l'origine dati sblocca la riga. Non tutte le origini dati supportano questo tipo di blocco.

Per altre informazioni su SQLSetPos, vedere Windows SDK. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

`CRecordset::Requery`

Ricompila (aggiorna) un recordset.

virtual BOOL Requery();

Valore restituito

Diverso da zero se il recordset è stato ricompilato correttamente; in caso contrario, 0.

Osservazioni:

Se vengono restituiti record, il primo di essi diventa il record corrente.

Affinché il recordset rifletta le aggiunte e le eliminazioni eseguite dall'utente o da altri utenti all'origine dati, è necessario ricompilare il recordset chiamando Requery. Se il recordset è un dynaset, riflette automaticamente gli aggiornamenti apportati dall'utente o da altri utenti ai relativi record esistenti (ma non aggiunte). Se il recordset è uno snapshot, è necessario chiamare Requery per riflettere le modifiche da parte di altri utenti e aggiunte ed eliminazioni.

Per un dynaset o uno snapshot, chiamare Requery ogni volta che si desidera ricompilare il recordset usando un nuovo filtro o ordinamento o nuovi valori di parametro. Impostare la nuova proprietà di filtro o ordinamento assegnando nuovi valori a m_strFilter e m_strSort prima di chiamare Requery. Impostare nuovi parametri assegnando nuovi valori ai membri dati dei parametri prima di chiamare Requery. Se le stringhe di filtro e ordinamento sono invariate, è possibile riutilizzare la query, migliorando le prestazioni.

Se il tentativo di ricompilare il recordset non riesce, il recordset viene chiuso. Prima di chiamare Requery, è possibile determinare se il recordset può essere rieseguito chiamando la CanRestart funzione membro. CanRestart non garantisce che Requery avrà esito positivo.

Attenzione

Chiamare Requery solo dopo aver chiamato Open.

Esempio

In questo esempio viene ricompilato un recordset per applicare un ordinamento diverso.

CCustomer rsCustSet(&m_dbCust);

// Open the recordset
rsCustSet.Open();

// Use the recordset ...

// Set the sort order and Requery the recordset
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");
if (!rsCustSet.CanRestart())
return;    // Unable to requery

if (!rsCustSet.Requery())
// Requery failed, so take action
AfxMessageBox(_T("Requery failed!"));

`CRecordset::SetAbsolutePosition`

Posiziona il recordset sul record corrispondente al numero di record specificato.

void SetAbsolutePosition(long nRows);

Parametri

nRows
Posizione ordinale in base uno per il record corrente nel recordset.

Osservazioni:

SetAbsolutePosition sposta il puntatore del record corrente in base a questa posizione ordinale.

Nota

Questa funzione membro non è valida nei recordset forward-only.

Per i recordset ODBC, un'impostazione di posizione assoluta pari a 1 fa riferimento al primo record nel recordset; un'impostazione pari a 0 si riferisce alla posizione iniziale del file (BOF).

È anche possibile passare valori negativi a SetAbsolutePosition. In questo caso, la posizione del recordset viene valutata dalla fine del recordset. Ad esempio, SetAbsolutePosition( -1 ) sposta il puntatore del record corrente all'ultimo record nel recordset.

Nota

La posizione assoluta non deve essere usata come numero di record surrogato. I segnalibri sono ancora il modo consigliato per conservare e tornare a una determinata posizione, poiché la posizione di un record cambia quando i record precedenti vengono eliminati. Inoltre, non è possibile assicurarsi che un determinato record avrà la stessa posizione assoluta se il recordset viene ricreato perché l'ordine dei singoli record all'interno di un recordset non è garantito a meno che non venga creato con un'istruzione SQL usando una ORDER BY clausola .

Per altre informazioni sulla navigazione e i segnalibri del recordset, vedere gli articoli Recordset: Scorrimento (ODBC) e Recordset: Segnalibri e posizioni assolute (ODBC).

`CRecordset::SetBookmark`

Posiziona il recordset nel record contenente il segnalibro specificato.

void SetBookmark(const CDBVariant& varBookmark);

Parametri

varBookmark
Riferimento a un CDBVariant oggetto contenente il valore del segnalibro per un record specifico.

Osservazioni:

Nota

Se i segnalibri non sono supportati o non sono disponibili, la chiamata SetBookmark genererà un'eccezione. I segnalibri non sono supportati nei recordset forward-only.

Per recuperare prima di tutto il segnalibro per il record corrente, chiamare GetBookmark, che salva il valore del segnalibro in un CDBVariant oggetto . Successivamente, è possibile tornare a tale record chiamando SetBookmark usando il valore del segnalibro salvato.

Nota

Dopo alcune operazioni del recordset, è necessario controllare la persistenza del segnalibro prima di chiamare SetBookmark. Ad esempio, se si recupera un segnalibro con GetBookmark e quindi si chiama Requery, il segnalibro potrebbe non essere più valido. Chiamare CDatabase::GetBookmarkPersistence per verificare se è possibile chiamare SetBookmarkin modo sicuro .

Per altre informazioni sui segnalibri e sulla navigazione dei recordset, vedere gli articoli Recordset: Segnalibri e posizioni assolute (ODBC) e Recordset: Scorrimento (ODBC).

`CRecordset::SetFieldDirty`

Contrassegna un membro dati di campo del recordset come modificato o invariato.

void SetFieldDirty(void* pv, BOOL bDirty = TRUE);

Parametri

pv
Contiene l'indirizzo di un membro dati di campo nel recordset o NULL. Se NULL, tutti i membri dati di campo nel recordset vengono contrassegnati. C++ NULL non è uguale a Null nella terminologia del database, ovvero "senza valore".

bDirty
TRUE se il membro dati del campo deve essere contrassegnato come "dirty" (modificato). In caso contrario FALSE , se il membro dati del campo deve essere contrassegnato come "pulito" (non modificato).

Osservazioni:

Contrassegnare i campi come invariati garantisce che il campo non sia aggiornato e restituisca meno traffico SQL.

Nota

Questa funzione membro non è applicabile ai recordset che usano il recupero delle righe bulk. Se è stato implementato il recupero di righe bulk, SetFieldDirty verrà restituita un'asserzione non riuscita. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

Il framework contrassegna i membri dei dati dei campi modificati per assicurarsi che vengano scritti nel record nell'origine dati dal meccanismo RFX (Record Field Exchange). La modifica del valore di un campo imposta in genere il campo dirty automaticamente, quindi raramente sarà necessario chiamare SetFieldDirty se stessi, ma a volte potrebbe essere necessario assicurarsi che le colonne vengano aggiornate in modo esplicito o inserite indipendentemente dal valore presente nel membro dati del campo.

Attenzione

Chiamare questa funzione membro solo dopo aver chiamato Edit o AddNew.

Se si usa NULL per il primo argomento della funzione, la funzione verrà applicata solo ai campi, non param ai outputColumn campi. Ad esempio, la chiamata

SetFieldNull(NULL);

imposta solo outputColumn i campi su NULL. param I campi non saranno interessati.

Per lavorare sui param campi, è necessario specificare l'indirizzo effettivo dell'utente param su cui si vuole lavorare, ad esempio:

SetFieldNull(&m_strParam);

Ciò significa che non è possibile impostare tutti i param campi su NULL, come è possibile con i outputColumn campi.

`CRecordset::SetFieldNull`

Contrassegna un membro dati di campo del recordset come Null (in particolare senza valore) o come non Null.

void SetFieldNull(void* pv, BOOL bNull = TRUE);

Parametri

pv
Contiene l'indirizzo di un membro dati di campo nel recordset o NULL. Se NULL, tutti i membri dati di campo nel recordset vengono contrassegnati. C++ NULL non è uguale a Null nella terminologia del database, ovvero "senza valore".

bNull
Diverso da zero se il membro dati del campo deve essere contrassegnato come senza valore (Null). In caso contrario, 0 se il membro dati del campo deve essere contrassegnato come non Null.

Osservazioni:

Quando si aggiunge un nuovo record a un recordset, tutti i membri dati del campo vengono inizialmente impostati su un valore Null e contrassegnati come "dirty" (modificati). Quando si recupera un record da un'origine dati, le relative colonne hanno già valori o sono Null.

Nota

Non chiamare questa funzione membro sui recordset che usano il recupero delle righe bulk. Se è stato implementato il recupero delle righe bulk, la chiamata SetFieldNull restituisce un'asserzione non riuscita. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

Se si desidera specificamente designare un campo del record corrente come non avere un valore, chiamare SetFieldNull con bNull impostato su TRUE per contrassegnarlo come Null. Se un campo è stato contrassegnato in precedenza su Null e si vuole assegnare un valore, impostarne il nuovo valore. Non è necessario rimuovere il flag Null con SetFieldNull. Per determinare se il campo può essere Null, chiamare IsFieldNullable.

Attenzione

Chiamare questa funzione membro solo dopo aver chiamato Edit o AddNew.

Se si usa NULL per il primo argomento della funzione, la funzione verrà applicata solo ai campi, non param ai outputColumn campi. Ad esempio, la chiamata

SetFieldNull(NULL);

imposta solo outputColumn i campi su NULL. param I campi non saranno interessati.

Per lavorare sui param campi, è necessario specificare l'indirizzo effettivo dell'utente param su cui si vuole lavorare, ad esempio:

SetFieldNull(&m_strParam);

Ciò significa che non è possibile impostare tutti i param campi su NULL, come è possibile con i outputColumn campi.

Nota

Quando si impostano i parametri su Null, una chiamata a SetFieldNull prima dell'apertura del recordset genera un'asserzione. In questo caso, chiamare SetParamNull.

SetFieldNull viene implementato tramite DoFieldExchange.

`CRecordset::SetLockingMode`

Imposta la modalità di blocco su blocco "ottimistico" (impostazione predefinita) o "pessimistico". Determina la modalità di blocco dei record per gli aggiornamenti.

void SetLockingMode(UINT nMode);

Parametri

nMode
Contiene uno dei valori seguenti di enum LockMode:

optimistic Il blocco ottimistico blocca il record da aggiornare solo durante la chiamata a Update.
pessimistic Il blocco pessimistico blocca il record non appena Edit viene chiamato e lo mantiene bloccato finché la Update chiamata non viene completata o si passa a un nuovo record.

Osservazioni:

Chiamare questa funzione membro se è necessario specificare quali di due strategie di blocco di record utilizzano il recordset per gli aggiornamenti. Per impostazione predefinita, la modalità di blocco di un recordset è optimistic. È possibile passare a una strategia di blocco più prudente pessimistic . Chiamare SetLockingMode dopo aver costruito e aperto l'oggetto recordset, ma prima di chiamare Edit.

`CRecordset::SetParamNull`

Contrassegna un parametro come Null (in particolare senza valore) o come non Null.

void SetParamNull(
    int nIndex,
    BOOL bNull = TRUE);

Parametri

nIndex
Indice in base zero del parametro.

bNull
Se TRUE (il valore predefinito), il parametro viene contrassegnato come Null. In caso contrario, il parametro viene contrassegnato come non Null.

Osservazioni:

A differenza di SetFieldNull, è possibile chiamare SetParamNull prima di aprire il recordset.

SetParamNull viene in genere usato con query predefinite (stored procedure).

`CRecordset::SetRowsetCursorPosition`

Sposta il cursore in una riga all'interno del set di righe corrente.

void SetRowsetCursorPosition(WORD wRow, WORD wLockType = SQL_LOCK_NO_CHANGE);

Parametri

wRow
Posizione in base unica di una riga nel set di righe corrente. Questo valore può variare da 1 alla dimensione del set di righe.

wLockType
Valore che indica come bloccare la riga dopo l'aggiornamento. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

Quando si implementa il recupero delle righe bulk, i record vengono recuperati da set di righe, in cui il primo record nel set di righe recuperato è il record corrente. Per creare un altro record all'interno del set di righe, chiamare SetRowsetCursorPosition. Ad esempio, è possibile combinare SetRowsetCursorPosition con la GetFieldValue funzione membro per recuperare dinamicamente i dati da qualsiasi record del recordset.

Per usare SetRowsetCursorPosition, è necessario aver implementato il recupero delle righe bulk specificando l'opzione CRecordset::useMultiRowFetch del dwOptions parametro nella Open funzione membro.

SetRowsetCursorPosition chiama la funzione SQLSetPosAPI ODBC . Il wLockType parametro specifica lo stato di blocco della riga dopo SQLSetPos l'esecuzione. Nella tabella seguente vengono descritti i valori possibili per wLockType.

`wLockType`	Descrizione
`SQL_LOCK_NO_CHANGE` (valore predefinito)	Il driver o l'origine dati garantisce che la riga si trova nello stesso stato bloccato o sbloccato precedentemente `SetRowsetCursorPosition` chiamato.
`SQL_LOCK_EXCLUSIVE`	Il driver o l'origine dati blocca la riga esclusivamente. Non tutte le origini dati supportano questo tipo di blocco.
`SQL_LOCK_UNLOCK`	Il driver o l'origine dati sblocca la riga. Non tutte le origini dati supportano questo tipo di blocco.

Per altre informazioni su SQLSetPos, vedere Windows SDK. Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

`CRecordset::SetRowsetSize`

Specifica il numero di record che si desidera recuperare durante un recupero.

virtual void SetRowsetSize(DWORD dwNewRowsetSize);

Parametri

dwNewRowsetSize
Numero di righe da recuperare durante un determinato recupero.

Osservazioni:

Questa funzione membro virtuale specifica il numero di righe che si desidera recuperare durante un singolo recupero quando si utilizza il recupero di righe bulk. Per implementare il recupero delle righe bulk, è necessario impostare l'opzione CRecordset::useMultiRowFetch nel dwOptions parametro della Open funzione membro.

Nota

La chiamata SetRowsetSize senza l'implementazione del recupero delle righe bulk comporterà un'asserzione non riuscita.

Chiamare SetRowsetSize prima di chiamare Open per impostare inizialmente le dimensioni del set di righe per il recordset. Le dimensioni predefinite del set di righe durante l'implementazione del recupero delle righe bulk sono 25.

Nota

Prestare attenzione quando si chiama SetRowsetSize. Se si alloca manualmente l'archiviazione per i dati (come specificato dall'opzione CRecordset::userAllocMultiRowBuffers del parametro dwOptions in Open), è necessario verificare se è necessario riallocare questi buffer di archiviazione dopo aver chiamato SetRowsetSize, ma prima di eseguire qualsiasi operazione di spostamento del cursore.

Per ottenere l'impostazione corrente per le dimensioni del set di righe, chiamare GetRowsetSize.

Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

`CRecordset::Update`

Completa un'operazione AddNew o Edit salvando i dati nuovi o modificati nell'origine dati.

virtual BOOL Update();

Valore restituito

Diverso da zero se un record è stato aggiornato correttamente; in caso contrario, 0 se non sono state modificate colonne. Se non sono stati aggiornati record o se sono stati aggiornati più record, viene generata un'eccezione. Viene generata anche un'eccezione per qualsiasi altro errore nell'origine dati.

Osservazioni:

Chiamare questa funzione membro dopo una chiamata alla AddNew funzione membro o Edit . Questa chiamata è necessaria per completare l'operazione AddNew o Edit .

Nota

Se è stato implementato il recupero delle righe bulk, non è possibile chiamare Update. In questo modo verrà restituita un'asserzione non riuscita. Sebbene la classe CRecordset non fornisca un meccanismo per l'aggiornamento di righe bulk di dati, è possibile scrivere funzioni personalizzate usando la funzione SQLSetPosAPI ODBC . Per altre informazioni sul recupero delle righe bulk, vedere Recordset: recupero di record in blocco (ODBC).

Sia AddNew che Edit preparare un buffer di modifica in cui vengono inseriti i dati aggiunti o modificati per il salvataggio nell'origine dati. Update salva i dati. Vengono aggiornati solo i campi contrassegnati o rilevati come modificati.

Se l'origine dati supporta le transazioni, è possibile effettuare la Update chiamata (e la relativa chiamata o Edit corrispondenteAddNew) di una transazione. Per altre informazioni sulle transazioni, vedere Transaction (ODBC).For more information about transactions, see Transaction (ODBC).

Attenzione

Se si chiama senza prima chiamare UpdateAddNew o Edit, Update genera un'eccezione CDBException. Se si chiama o Edit, è necessario chiamare UpdateAddNew prima di chiamare un'operazione Move o prima di chiudere il recordset o la connessione all'origine dati. In caso contrario, le modifiche andranno perse senza notifica.

Per informazioni dettagliate sulla gestione degli Update errori, vedere Recordset: How Recordsets Update Records (ODBC).

Esempio

vedere Transazione: esecuzione di una transazione in un oggetto Recordset (ODBC).See Transaction: Performing a Transaction in a Recordset (ODBC).

Vedi anche

Classe CObject
Grafico gerarchia
Classe CDatabase
Classe CRecordView

Condividi tramite

Classe CRecordset

Sintassi

Membri

Costruttori pubblici

Metodi pubblici

Membri dati pubblici

Osservazioni:

Gerarchia di ereditarietà

Requisiti

CRecordset::AddNew

Osservazioni:

Esempio

CRecordset::CanAppend

Valore restituito

CRecordset::CanBookmark

Valore restituito

Osservazioni:

CRecordset::Cancel

Osservazioni:

CRecordset::CancelUpdate

Osservazioni:

CRecordset::CanRestart

Valore restituito

CRecordset::CanScroll

Valore restituito

Osservazioni:

CRecordset::CanTransact

Valore restituito

Osservazioni:

CRecordset::CanUpdate

Valore restituito

Osservazioni:

CRecordset::CheckRowsetError

Parametri

Osservazioni:

CRecordset::Close

Osservazioni:

Esempio

CRecordset::CRecordset

Parametri

Osservazioni:

Esempio

CRecordset::Delete

Osservazioni:

Esempio

CRecordset::DoBulkFieldExchange

Parametri

Osservazioni:

CRecordset::DoFieldExchange

Parametri

Osservazioni:

CRecordset::Edit

Osservazioni:

Esempio

CRecordset::FlushResultSet

Valore restituito

Osservazioni:

Esempio

CRecordset::GetBookmark

Parametri

Osservazioni:

CRecordset::GetDefaultConnect

Valore restituito

Osservazioni:

CRecordset::GetDefaultSQL

Valore restituito

Osservazioni:

CRecordset::GetFieldValue

Parametri

Osservazioni:

Esempio

CRecordset::GetODBCFieldCount

Valore restituito

Osservazioni:

CRecordset::GetODBCFieldInfo

Parametri

Osservazioni:

CRecordset::GetRecordCount

Valore restituito

Classe `CRecordset`

`CRecordset::AddNew`

`CRecordset::CanAppend`

`CRecordset::CanBookmark`

`CRecordset::Cancel`

`CRecordset::CancelUpdate`

`CRecordset::CanRestart`

`CRecordset::CanScroll`

`CRecordset::CanTransact`

`CRecordset::CanUpdate`

`CRecordset::CheckRowsetError`

`CRecordset::Close`

`CRecordset::CRecordset`

`CRecordset::Delete`

`CRecordset::DoBulkFieldExchange`

`CRecordset::DoFieldExchange`

`CRecordset::Edit`

`CRecordset::FlushResultSet`

`CRecordset::GetBookmark`

`CRecordset::GetDefaultConnect`

`CRecordset::GetDefaultSQL`

`CRecordset::GetFieldValue`

`CRecordset::GetODBCFieldCount`

`CRecordset::GetODBCFieldInfo`

`CRecordset::GetRecordCount`

`CRecordset::GetRowsetSize`

`CRecordset::GetRowsFetched`

`CRecordset::GetRowStatus`

`CRecordset::GetStatus`

`CRecordset::GetSQL`

`CRecordset::GetTableName`

`CRecordset::IsBOF`

`CRecordset::IsDeleted`

`CRecordset::IsEOF`

`CRecordset::IsFieldDirty`

`CRecordset::IsFieldNull`

`CRecordset::IsFieldNullable`

`CRecordset::IsOpen`

`CRecordset::m_hstmt`

`CRecordset::m_nFields`

`CRecordset::m_nParams`

`CRecordset::m_pDatabase`

`CRecordset::m_strFilter`

`CRecordset::m_strSort`

`CRecordset::Move`

`CRecordset::MoveFirst`

`CRecordset::MoveLast`