Classe CRecordset

Representa um conjunto de registros selecionados de uma fonte de dados.

Sintaxe

class CRecordset : public CObject

Membros

Construtores públicos

Nome	Descrição
CRecordset::CRecordset	Constrói um objeto CRecordset. Sua classe derivada deve fornecer um construtor que chame este.

Métodos públicos

Nome	Descrição
CRecordset::AddNew	Prepara-se para adicionar um novo registro. Chame Update para concluir a adição.
CRecordset::CanAppend	Retorna diferente de zero se novos registros puderem ser adicionados ao conjunto de registros por meio da função de membro AddNew.
CRecordset::CanBookmark	Retornará diferente de zero se o conjunto de registros der suporte a indicadores.
CRecordset::Cancel	Cancela uma operação assíncrona ou um processo de um segundo thread.
CRecordset::CancelUpdate	Cancela todas as atualizações pendentes devido a uma operação AddNew ou Edit.
CRecordset::CanRestart	Retorna diferente de zero se Requery puder ser chamado para executar a consulta do conjunto de registros novamente.
CRecordset::CanScroll	Retorna diferente de zero se você puder percorrer os registros.
CRecordset::CanTransact	Retornará diferente de zero se a fonte de dados der suporte a transações.
CRecordset::CanUpdate	Retornará diferente de zero se o conjunto de registros puder ser atualizado (você pode adicionar, atualizar ou excluir registros).
CRecordset::CheckRowsetError	Chamado para lidar com erros gerados durante a busca de registros.
CRecordset::Close	Fecha o conjunto de registros e o ODBC HSTMT associado a ele.
CRecordset::Delete	Exclui o registro atual do conjunto de registros. Você deve avançar explicitamente para outro registro após a exclusão.
CRecordset::DoBulkFieldExchange	Chamado para trocar linhas em massa de dados da fonte de dados para o conjunto de registros. Implementa a troca de campo de registro em massa (RFX em massa).
CRecordset::DoFieldExchange	Chamado para trocar dados (em ambas as direções) entre os membros de dados de campo do conjunto de registros e o registro correspondente na fonte de dados. Implementa a troca de campo de registro (RFX).
CRecordset::Edit	Prepara-se para alterações no registro atual. Chame Update para concluir a edição.
CRecordset::FlushResultSet	Retorna diferente de zero se houver outro conjunto de resultados a ser recuperado ao usar uma consulta predefinida.
CRecordset::GetBookmark	Atribui o valor de indicador de um registro ao objeto de parâmetro.
CRecordset::GetDefaultConnect	Chamado para obter a cadeia de conexão padrão.
CRecordset::GetDefaultSQL	Chamado para obter a cadeia de caracteres SQL padrão a ser executada.
CRecordset::GetFieldValue	Retorna o valor de um campo em um conjunto de registros.
CRecordset::GetODBCFieldCount	Obtém o número de campos no conjunto de registros.
CRecordset::GetODBCFieldInfo	Retorna tipos específicos de informações sobre os campos em um conjunto de registros.
CRecordset::GetRecordCount	Retorna o número de registros no conjunto de registros.
CRecordset::GetRowsetSize	Retorna o número de registros que você deseja recuperar durante uma única busca.
CRecordset::GetRowsFetched	Retorna o número real de linhas recuperadas durante uma busca.
CRecordset::GetRowStatus	Retorna o status da linha após uma busca.
CRecordset::GetSQL	Obtém a cadeia de caracteres SQL usada para selecionar registros para o conjunto de registros.
CRecordset::GetStatus	Obtém o status do conjunto de registros: o índice do registro atual e se uma contagem final dos registros foi obtida.
CRecordset::GetTableName	Obtém o nome da tabela na qual o conjunto de registros está baseada.
CRecordset::IsBOF	Retornará diferente de zero se o conjunto de registros tiver sido posicionado antes do primeiro registro. Não há registro atual.
CRecordset::IsDeleted	Retornará diferente de zero se o conjunto de registros estiver posicionado em um registro excluído.
CRecordset::IsEOF	Retornará diferente de zero se o conjunto de registros tiver sido posicionado depois do último registro. Não há registro atual.
CRecordset::IsFieldDirty	Retornará diferente de zero se o campo especificado no registro atual tiver sido alterado.
CRecordset::IsFieldNull	Retornará diferente de zero se o campo especificado no registro atual for nulo (sem valor).
CRecordset::IsFieldNullable	Retornará diferente de zero se o campo especificado no registro atual puder ser definido como nulo (sem valor).
CRecordset::IsOpen	Retornará diferente de zero se Open tiver sido chamado anteriormente.
CRecordset::Move	Posiciona o conjunto de registros para um número especificado de registros do registro atual em qualquer direção.
CRecordset::MoveFirst	Posiciona o registro atual no primeiro registro no conjunto de registros. Teste para IsBOF primeiro.
CRecordset::MoveLast	Posiciona o registro atual no último registro ou no último conjunto de linhas. Teste para IsEOF primeiro.
CRecordset::MoveNext	Posiciona o registro atual no próximo registro ou no próximo conjunto de linhas. Teste para IsEOF primeiro.
CRecordset::MovePrev	Posiciona o registro atual no registro anterior ou no conjunto de linhas anterior. Teste para IsBOF primeiro.
CRecordset::OnSetOptions	Chamado para definir opções (usadas na seleção) para a instrução ODBC especificada.
CRecordset::OnSetUpdateOptions	Chamado para definir opções (usadas na atualização) para a instrução ODBC especificada.
CRecordset::Open	Abre o conjunto de registros recuperando a tabela ou executando a consulta que o conjunto de registros representa.
CRecordset::RefreshRowset	Atualiza os dados e o status das linhas especificadas.
CRecordset::Requery	Executa a consulta do conjunto de registros novamente para atualizar os registros selecionados.
CRecordset::SetAbsolutePosition	Posiciona o conjunto de registros no registro correspondente ao número de registro especificado.
CRecordset::SetBookmark	Posiciona o conjunto de registros no registro especificado pelo indicador.
CRecordset::SetFieldDirty	Marca o campo especificado no registro atual conforme alterado.
CRecordset::SetFieldNull	Define o valor do campo especificado no registro atual como Nulo (sem valor).
CRecordset::SetLockingMode	Define o modo de bloqueio como bloqueio "otimista" (o padrão) ou bloqueio "pessimista". Determina como os registros são bloqueados para atualizações.
CRecordset::SetParamNull	Define o valor atual do parâmetro especificado como Null (sem valor).
CRecordset::SetRowsetCursorPosition	Posiciona o cursor na linha especificada dentro do conjunto de linhas.
CRecordset::SetRowsetSize	Especifica o número de registros que você deseja recuperar durante uma busca.
CRecordset::Update	Conclui uma operação AddNew ou Edit salvando os dados novos ou editados na fonte de dados.

Membros de dados públicos

Nome	Descrição
CRecordset::m_hstmt	Contém o identificador de instrução ODBC do conjunto de registros. Digite HSTMT.
CRecordset::m_nFields	Contém o número de membros de dados de campo no conjunto de registros. Digite UINT.
CRecordset::m_nParams	Contém o número de membros de dados de parâmetro no conjunto de registros. Digite UINT.
CRecordset::m_pDatabase	Contém um ponteiro para o objeto CDatabase por meio do qual o conjunto de registros está conectado a uma fonte de dados.
CRecordset::m_strFilter	Contém um CString que especifica uma cláusula WHERE da linguagem SQL (SQL). Usado como um filtro para selecionar apenas os registros que atendem a determinados critérios.
CRecordset::m_strSort	Contém uma CString que especifica uma cláusula ORDER BY SQL. Usada para controlar como os registros são classificados.

Comentários

Conhecidos como "conjuntos de registros", os objetos CRecordset normalmente são usados em duas formas: dynasets e snapshots. Um dynaset permanece sincronizado com as atualizações de dados feitas por outros usuários. Um snapshot é uma exibição estática dos dados. Cada forma representa um conjunto de registros corrigidos no momento em que o conjunto de registros é aberto. Quando você rola até um registro em um dynaset, ele reflete as alterações feitas no registro, por outros usuários ou por outros conjuntos de registros em seu aplicativo.

Para trabalhar com qualquer tipo de conjunto de registros, normalmente você deriva de CRecordset uma classe de conjunto de registros específica do aplicativo. Os conjuntos de registros selecionam registros de uma fonte de dados e, em seguida, você pode:

• Percorra os registros.

• Atualizar os registros e especifique um modo de bloqueio.

• Filtrar o conjunto de registros para restringir quais registros ele seleciona dentre os disponíveis na fonte de dados.

• Organizar o conjunto de registros.

• Parametrizar o conjunto de registros para personalizar sua seleção com informações não conhecidas até o tempo de execução.

Para usar sua classe, abra um banco de dados e construa um objeto de conjunto de registros, passando no construtor um ponteiro para o objeto CDatabase. Em seguida, chame a função de membro Open do conjunto de registros, na qual você pode especificar se o objeto é um dynaset ou um snapshot. Chamar Open seleciona dados da fonte de dados. Depois que o objeto recordset for aberto, use suas funções de membro e membros de dados para percorrer os registros e operá-los. As operações disponíveis dependem de o objeto ser um dynaset ou um snapshot, atualizável ou somente leitura [isso depende da funcionalidade da fonte de dados ODBC (Open Database Connectivity)] e se você implementou a busca de linhas em massa. Para atualizar registros que podem ter sido alterados ou adicionados desde a chamada de Open, chame a função de membro Requery do objeto. Chame a função de membro Close do objeto e destrua o objeto quando terminar.

Em uma classe derivada CRecordset, a troca de campo de registro (RFX) ou troca de campo de registro em massa (RFX em massa) é usada para dar suporte à leitura e à atualização de campos de registro.

Para obter mais informações sobre conjuntos de registros e troca de campos de registro, consulte os artigos Visão geral: Programação de banco de dados, Conjunto de registros (ODBC),, Conjunto de registros: buscando registros em massa (ODBC) e Troca de campos de registro (RFX). Para obter um foco em dynasets e instantâneos, consulte os artigos Dynaset e Snapshot.

Hierarquia de herança

CObject

CRecordset

Requisitos

Cabeçalho: afxdb.h

CRecordset::AddNew

Prepara-se para adicionar um novo registro à tabela.

virtual void AddNew();

Comentários

Você deve chamar a função membro Requery para ver o registro recém-adicionado. Os campos do registro são inicialmente Null. (Na terminologia do banco de dados, Null significa "sem valor" e não é o mesmo que NULL em C++.) Para concluir a operação, você deve chamar a função de membro Update. Update salva as alterações feitas na fonte de dados.

AddNew prepara um novo registro vazio usando os membros de dados de campo do conjunto de registros. Depois de chamar AddNew, defina os valores desejados nos membros de dados de campo do conjunto de registros. (Você não precisa chamar a função de membro Edit para essa finalidade; use Edit apenas para registros existentes.) Quando você chama Update, os valores alterados nos membros de dados do campo são salvos na fonte de dados.

Se o banco de dados der suporte a transações, você poderá tornar a chamada AddNew parte de uma transação. Para obter mais informações sobre transações, confira a classe CDatabase. Chame CDatabase::BeginTrans antes de chamar AddNew.

É ilegal chamar AddNew para um conjunto de registros cuja função de membro Open não foi chamada. Um CDBException será gerado se você chamar AddNew para um conjunto de registros que não pode ser acrescentado. Você pode determinar se o conjunto de registros pode ser atualizado chamando CanAppend.

Para obter mais informações, consulte os seguintes artigos: Recordset: Como conjuntos de registros atualizam registos (ODBC), Conjunto de registros: Adicionar, atualizar e excluir registros (ODBC) e Transação (ODBC).

Exemplo

confira Transação: realizando uma transação em um conjunto de registros (ODBC).

CRecordset::CanAppend

Determina se o conjunto de registros aberto anteriormente permite que você adicione novos registros.

BOOL CanAppend() const;

Valor retornado

Diferente de zero se o conjunto de registros permitir a adição de novos registros; caso contrário, 0. CanAppend retornará 0 se você tiver aberto o conjunto de registros como somente leitura.

CRecordset::CanBookmark

Determina se o conjunto de registros permite que você marque registros usando indicadores.

BOOL CanBookmark() const;

Valor retornado

Diferente de zero se o conjunto de registros der suporte a indicadores; caso contrário, será zero.

Comentários

Essa função é independente da opção CRecordset::useBookmarks no parâmetro dwOptions da função de membro Open. CanBookmark indica se o driver ODBC fornecido e o tipo de cursor dão suporte a indicadores. CRecordset::useBookmarks indica se os indicadores estarão disponíveis, desde que sejam compatíveis.

Para obter mais informações sobre indicadores e navegação de conjunto de registros, consulte os artigos Conjunto de registros: indicadores e posições absolutas (ODBC) e Conjunto de registros: deslocamento (ODBC).

CRecordset::Cancel

Solicita que a fonte de dados cancele uma operação assíncrona em andamento ou um processo de um segundo thread.

void Cancel();

Comentários

As classes ODBC do MFC não usam mais processamento assíncrono; para executar uma operação assíncrona, você deve chamar diretamente a função SQLSetConnectOptionda API ODBC. Para obter mais informações, confira "Executando funções de forma assíncrona" no Guia do programador do SDK do ODBC.

CRecordset::CancelUpdate

Cancela todas as atualizações pendentes, causadas por uma operação Edit ou AddNew, antes Update de ser chamada.

void CancelUpdate();

Comentários

Se a verificação automática de campo sujo estiver habilitada, CancelUpdate restaurará as variáveis de membro para os valores que tinham antes Edit ou AddNew foram chamados; caso contrário, as alterações de valor permanecerão. Por padrão, a verificação automática de campo é habilitada quando o conjunto de registros é aberto. Para desabilitá-lo, você deve especificar o CRecordset::noDirtyFieldCheck no parâmetrodwOptions da função de membro Open.

Para obter mais informações sobre como atualizar dados, consulte Conjunto de registros: adicionar, atualizar e excluir registros (ODBC).

CRecordset::CanRestart

Determina se o conjunto de registros permite reiniciar sua consulta (para atualizar seus registros) chamando a função de membro Requery.

BOOL CanRestart() const;

Valor retornado

Diferente de zero se a nova consulta for permitida; caso contrário, 0.

CRecordset::CanScroll

Determina se o conjunto de registros permite o deslocamento.

BOOL CanScroll() const;

Valor retornado

Diferente de zero se o conjunto de registros permitir o deslocamento; caso contrário, 0.

Comentários

Para obter mais informações sobre deslocamento, confira Conjunto de registros: deslocamento (ODBC).

CRecordset::CanTransact

Determina se o conjunto de registros permite transações.

BOOL CanTransact() const;

Valor retornado

Diferente de zero se o conjunto de registros permitir transações; caso contrário, 0.

Comentários

Para obter mais informações, confira Transação (ODBC).

CRecordset::CanUpdate

Determina se o conjunto de registros pode ser atualizado.

BOOL CanUpdate() const;

Valor retornado

Diferente de zero se o conjunto de registros puder ser atualizado; caso contrário, 0.

Comentários

Um conjunto de registros poderá ser somente leitura se a fonte de dados subjacente for somente leitura ou se você especificou CRecordset::readOnly no parâmetro dwOptions quando abriu o conjunto de registros.

CRecordset::CheckRowsetError

Chamado para lidar com erros gerados durante a busca de registros.

virtual void CheckRowsetError(RETCODE nRetCode);

Parâmetros

nRetCode
Um código de retorno da função de API ODBC. Para obter detalhes, consulte Observações.

Comentários

Essa função de membro virtual lida com erros que ocorrem quando os registros são buscados e é útil durante a busca de linhas em massa. Talvez você queira considerar a substituição de CheckRowsetError para implementar seu próprio tratamento de erros.

CheckRowsetError é chamado automaticamente em uma operação de navegação de cursor, como Open, Requery ou qualquer operação Move. Ele é passado o valor retornado da função de API ODBC SQLExtendedFetch. A tabela a seguir lista os possíveis valores do parâmetro nRetCode.

nRetCode	Descrição
SQL_SUCCESS	Função concluída com êxito; nenhuma informação adicional está disponível.
SQL_SUCCESS_WITH_INFO	Função concluída com êxito, possivelmente com um erro não fatal. Informações adicionais podem ser obtidas chamando SQLError.
SQL_NO_DATA_FOUND	Todas as linhas do conjunto de resultados foram buscadas.
SQL_ERROR	Falha na função. Informações adicionais podem ser obtidas chamando SQLError.
SQL_INVALID_HANDLE	Falha na função devido a um identificador de ambiente, identificador de conexão ou identificador de instrução inválido. Isso indica um erro de programação. Não há nenhuma informação adicional disponível de SQLError.
SQL_STILL_EXECUTING	Uma função que foi iniciada de forma assíncrona ainda está em execução. Por padrão, o MFC nunca passará esse valor para CheckRowsetError; o MFC continuará chamando SQLExtendedFetch até que ele não retorne mais SQL_STILL_EXECUTING.

Para obter mais informações sobre SQLError, consulte o SDK do Windows. Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

CRecordset::Close

Fecha o conjunto de registros.

virtual void Close();

Comentários

O ODBC HSTMT e toda a memória que a estrutura alocada para o conjunto de registros são desalocados. Normalmente, após a chamar Close, você exclui o objeto do conjunto de registros C++ se ele foi alocado com new.

Você pode chamar Open novamente depois de chamar Close. Isso permite reutilizar o objeto do conjunto de registros. A alternativa é chamar Requery.

Exemplo

// 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

Constrói um objeto CRecordset.

CRecordset(CDatabase* pDatabase = NULL);

Parâmetros

pDatabase
Contém um ponteiro para um objeto CDatabase ou o valor NULL. Se não for NULL e a função de membro Open do objeto CDatabase não tiver sido chamada para conectá-la à fonte de dados, o conjunto de registros tentará abri-la para você durante sua própria chamada Open. Se você passar NULL, um objeto CDatabase será construído e conectado para você usando as informações de fonte de dados especificadas se você deu origem à classe de conjunto de registros com ClassWizard.

Comentários

Você pode usar CRecordset diretamente ou derivar uma classe específica do aplicativo de CRecordset. Você pode usar ClassWizard para derivar suas classes de conjunto de registros.

Passe NULL para o construtor do conjunto de registros para que um objeto CDatabase seja construído e conectado automaticamente. Esse é uma abreviação útil que não exige que você construa e conecte um objeto CDatabase antes de construir seu conjunto de registros.

Exemplo

Para obter mais informações, confira Conjunto de registros: declarando uma classe para uma tabela (ODBC).

CRecordset::Delete

Exclui o registro atual.

virtual void Delete();

Comentários

Após uma exclusão bem-sucedida, os membros de dados de campo do conjunto de registros são definidos como um valor Null e você deve chamar explicitamente uma das funções Move para sair do registro excluído. Depois de sair do registro excluído, não é possível retornar a ele. Se o banco de dados der suporte a transações, você poderá tornar sua chamada Delete parte de uma transação. Para obter mais informações, confira Transação (ODBC).

Diferentemente de AddNew e Edit, uma chamada para Delete não é seguida por uma chamada para Update. Se uma chamada Delete falhar, os membros dos dados do campo ficarão inalterados.

Exemplo

Este exemplo mostra um conjunto de registros criado no quadro de uma função. O exemplo pressupõe a existência de m_dbCust, uma variável de membro do tipo CDatabase já conectada à fonte de dados.

// 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

Chamado para trocar linhas em massa de dados da fonte de dados para o conjunto de registros. Implementa a troca de campo de registro em massa (RFX em massa).

virtual void DoBulkFieldExchange(CFieldExchange* pFX);

Parâmetros

pFX
Um ponteiro para um objeto CFieldExchange. A estrutura já terá configurado esse objeto para especificar um contexto para a operação de troca de campo.

Comentários

Quando a busca em massa de linhas é implementada, a estrutura chama essa função membro para transferir automaticamente dados da fonte de dados para o objeto do conjunto de registros. DoBulkFieldExchange também associa seus membros de dados de parâmetro, se houver, a espaços reservados de parâmetro na cadeia de caracteres de instrução SQL para a seleção do conjunto de registros.

Se a busca em linha em massa não for implementada, a estrutura chamará DoFieldExchange. Para implementar a busca de linhas em massa, você deve especificar a opção CRecordset::useMultiRowFetch do parâmetro dwOptions na função de membro Open.

A troca de campo de registro em massa (RFX em massa) é semelhante à troca de campo de registro (RFX). Os dados são transferidos automaticamente da fonte de dados para o objeto do conjunto de registros. No entanto, você não pode chamarAddNew, Edit, Delete ou Update para transferir alterações de volta para a fonte de dados. Atualmente, a classe CRecordset não fornece um mecanismo para atualizar linhas de dados em massa, porém, você pode escrever suas próprias funções usando a função API ODBC SQLSetPos.

O ClassWizard não dá suporte à troca de campo de registro em massa; portanto, você deve substituir DoBulkFieldExchange manualmente escrevendo chamadas para as funções RFX em massa. Para saber mais sobre essas funções, confira Funções de troca de campo de registro.

Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC). Para consultar informações relacionadas, confira Troca de campo de registro (RFX).

CRecordset::DoFieldExchange

Chamado para trocar dados (em ambas as direções) entre os membros de dados de campo do conjunto de registros e o registro correspondente na fonte de dados. Implementa a troca de campo de registro (RFX).

virtual void DoFieldExchange(CFieldExchange* pFX);

Parâmetros

pFX
Um ponteiro para um objeto CFieldExchange. A estrutura já terá configurado esse objeto para especificar um contexto para a operação de troca de campo.

Comentários

Quando a busca de linhas em massa não é implementada, a estrutura chama essa função de membro para trocar dados automaticamente entre os membros de dados de campo do objeto do conjunto de registros e as colunas correspondentes do registro atual na fonte de dados. DoFieldExchange também associa seus membros de dados de parâmetro, se houver, a espaços reservados de parâmetro na cadeia de caracteres de instrução SQL para a seleção do conjunto de registros.

Se a busca de linhas em massa não for implementada, a estrutura chamará DoBulkFieldExchange. Para implementar a busca de linhas em massa, você deve especificar a opção CRecordset::useMultiRowFetch do parâmetro dwOptions na função de membro Open.

A troca de dados de campo, chamada de troca de campo de registro (RFX), funciona em ambas as direções: dos membros de dados de campo do objeto do conjunto de registros aos campos do registro na fonte de dados e do registro na fonte de dados para o objeto do conjunto de registros.

A única ação que você normalmente deve tomar para implementar DoFieldExchange para sua classe de conjunto de registros derivada é criar a classe com ClassWizard e especificar os nomes e tipos de dados dos membros de dados do campo. Você também pode adicionar código ao que o ClassWizard grava para especificar membros de dados de parâmetro ou para lidar com todas as colunas associadas dinamicamente. Para obter mais informações, confira Conjunto de registros: associando dinamicamente colunas de dados (ODBC).

Quando você declara sua classe de conjunto de registros derivada com ClassWizard, o assistente grava uma substituição de DoFieldExchange para você, que se assemelha ao exemplo a seguir:

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);
}

Para saber mais sobre as funções RFX, confira Funções de troca de campo de registro.

Para obter mais exemplos e detalhes sobre DoFieldExchange, confira Troca de campo de registro: como a RFX funciona. Para obter informações sobre RFX, confira Troca de campo de registro.

CRecordset::Edit

Permite alterações no registro atual.

virtual void Edit();

Comentários

Depois de chamar Edit, você pode alterar os membros de dados do campo redefinindo diretamente seus valores. A operação é concluída quando você chama a função de membro Update para salvar suas alterações na fonte de dados.

Edit salva os valores dos membros de dados do conjunto de registros. Se você chamar Edit, fizer alterações e chamar Edit novamente, os valores do registro serão restaurados para o que eram antes da primeira chamada Edit.

Em alguns casos, é recomendável atualizar uma coluna tornando-a Null (sem dados). Para fazer isso, chame SetFieldNull com um parâmetro TRUE para marcar o campo Null; isso também faz com que a coluna seja atualizada. Se você quiser que um campo seja gravado na fonte de dados mesmo que seu valor não tenha sido alterado, chame SetFieldDirty com um parâmetro TRUE. Isso funciona mesmo se o campo tivesse o valor Null.

Se o banco de dados der suporte a transações, você poderá tornar sua chamada Edit parte de uma transação. Chame CDatabase::BeginTrans antes de chamar Edit e depois que o conjunto de registros for aberto. Além disso, chamar CDatabase::CommitTrans não substitui a chamada de Update para concluir a operação Edit. Para obter mais informações sobre transações, confira a classe CDatabase.

Dependendo do modo de bloqueio atual, o registro que está sendo atualizado pode ser bloqueado por Edit até que você chame Update ou se desloque para outro registro ou ele só poderá ser bloqueado durante a chamada de Edit. você pode alterar o modo de bloqueio com SetLockingMode.

O valor anterior do registro atual será restaurado se você rolar para um novo registro antes de chamar Update. Um CDBException será gerado se você chamar Edit para um conjunto de registros que não pode ser atualizado ou se não houver nenhum registro atual.

Para obter mais informações, confira os artigos Transação (ODBC) e Conjunto de registros: registros de bloqueio (ODBC).

Exemplo

// 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 o próximo conjunto de resultados de uma consulta predefinida (procedimento armazenado), se houver vários conjuntos de resultados.

BOOL FlushResultSet();

Valor retornado

Diferente de zero se houver mais conjuntos de resultados a serem recuperados; caso contrário, 0.

Comentários

Você deve chamar FlushResultSet somente quando terminar de usar o cursor no conjunto de resultados atual. Quando você recupera o próximo conjunto de resultados chamando FlushResultSet, seu cursor não é válido nesse conjunto de resultados; você deve chamar a função de membro MoveNext depois de chamar FlushResultSet.

Se uma consulta predefinida usa um parâmetro de saída ou parâmetros de entrada/saída, você deve chamar FlushResultSet até que ela retorne FALSE (o valor 0) para obter esses valores de parâmetro.

FlushResultSet chama a função de API ODBC SQLMoreResults. Se SQLMoreResults retornar SQL_ERROR ou SQL_INVALID_HANDLE, então FlushResultSet gerará uma exceção. Para obter mais informações sobre SQLMoreResults, consulte o SDK do Windows.

O procedimento armazenado precisa ter campos associados se você quiser chamar FlushResultSet.

Exemplo

O código a seguir pressupõe que COutParamRecordset seja um objeto derivado de CRecordset com base em uma consulta predefinida com um parâmetro de entrada e um parâmetro de saída e com vários conjuntos de resultados. Observe a estrutura da substituição de 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

Obtém o valor do indicador para o registro atual.

void GetBookmark(CDBVariant& varBookmark);

Parâmetros

varBookmark
Uma referência a um objeto CDBVariant que representa o indicador no registro atual.

Comentários

Para determinar se há suporte para indicadores no conjunto de registros, chame CanBookmark. Para disponibilizar indicadores se eles tiverem suporte, você deve definir a opção CRecordset::useBookmarks no parâmetro dwOptions da função de membro Open.

GetBookmark atribui o valor do indicador para o registro atual a um objeto CDBVariant. Para retornar a esse registro a qualquer momento depois de mover para um registro diferente, chame SetBookmark com o objeto correspondente CDBVariant.

Para obter mais informações sobre indicadores e navegação de conjunto de registros, consulte os artigos Conjunto de registros: indicadores e posições absolutas (ODBC) e Conjunto de registros: deslocamento (ODBC).

CRecordset::GetDefaultConnect

Chamado para obter a cadeia de conexão padrão.

virtual CString GetDefaultConnect();

Valor retornado

Um CString que contém a cadeia de conexão padrão.

Comentários

A estrutura chama essa função de membro para obter a cadeia de conexão padrão da fonte de dados na qual o conjunto de registros se baseia. ClassWizard implementa essa função para você identificando a mesma fonte de dados usada em ClassWizard para obter informações sobre tabelas e colunas. Você provavelmente achará conveniente confiar nessa conexão padrão ao desenvolver seu aplicativo. Mas a conexão padrão pode não ser apropriada para os usuários do aplicativo. Se esse for o caso, você deverá reimplementar essa função, descartando a versão do ClassWizard. Para obter mais informações sobre cadeias de conexão, consulte Fonte de dados (ODBC).

CRecordset::GetDefaultSQL

Chamado para obter a cadeia de caracteres SQL padrão a ser executada.

virtual CString GetDefaultSQL();

Valor retornado

Um CString que contém a instrução SQL padrão.

Comentários

A estrutura chama essa função membro para obter a instrução SQL padrão na qual o conjunto de registros se baseia. Pode ser um nome de tabela ou uma instrução SQL SELECT.

Você define indiretamente a instrução SQL padrão declarando sua classe de conjunto de registros com ClassWizard, e ClassWizard executa essa tarefa para você.

Se você precisar da cadeia de caracteres de instrução SQL para seu próprio uso, chame GetSQL, que retorna a instrução SQL usada para selecionar os registros do conjunto de registros quando ele foi aberto. Você pode editar a cadeia de caracteres SQL padrão na substituição de GetDefaultSQL da sua classe. Por exemplo, você pode especificar uma chamada para uma consulta predefinida usando uma instrução CALL. (Observe, no entanto, que, se você editar GetDefaultSQL, também precisará modificar m_nFields para corresponder ao número de colunas na fonte de dados.)

Para obter mais informações, confira Conjunto de registros: declarando uma classe para uma tabela (ODBC).

CRecordset::GetFieldValue

Recupera dados de campo no registro atual.

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);

Parâmetros

lpszName
O nome de um campo.

varValue Uma referência a um objeto CDBVariant que armazenará o valor do campo.

nFieldType
O tipo de dados ODBC C do campo. Usando o valor padrão, DEFAULT_FIELD_TYPE, força GetFieldValue a determinar o tipo de dados C do tipo de dados SQL, com base na tabela a seguir. Caso contrário, você pode especificar o tipo de dados diretamente ou escolher um tipo de dados compatível; por exemplo, você pode armazenar qualquer tipo de dados em SQL_C_CHAR.

Tipos de dados do C	Tipo de dados 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

Para obter mais informações sobre tipos de dados ODBC, consulte os tópicos "Tipos de Dados SQL" e "Tipos de Dados C" no Apêndice D do SDK do Windows.

nIndex
O índice de base zero do campo.

strValue
Uma referência a um objeto CString que armazenará o valor do campo convertido em texto, independentemente do tipo de dados do campo.

Comentários

Você pode pesquisar um campo por nome ou por índice. Você pode armazenar o valor do campo em um objeto CDBVariant ou objeto CString.

Se você tiver implementado a busca de linhas em massa, o registro atual sempre será posicionado no primeiro registro em um conjunto de linhas. Para usar GetFieldValue em um registro dentro de um determinado conjunto de linhas, primeiro você deve chamar a função de membro SetRowsetCursorPosition para mover o cursor para a linha desejada dentro desse conjunto de linhas. Em seguida, chame GetFieldValue para essa linha. Para implementar a busca de linhas em massa, você deve especificar a opção CRecordset::useMultiRowFetch do parâmetro dwOptions na função de membro Open.

Você pode usar GetFieldValue para buscar dinamicamente campos em tempo de execução em vez de vinculá-los estaticamente no momento do projeto. Por exemplo, se você tiver declarado um objeto de conjunto de registros diretamente de CRecordset, deverá usar GetFieldValue para recuperar os dados de campo; a RFX (troca de campo de registro) ou a troca de campo de registro em massa (RFX em massa) não será implementada.

GetFieldValue chama a função de API ODBC SQLGetData. Se o driver gerar o valor SQL_NO_TOTAL para o comprimento real do valor do campo, GetFieldValue gerará uma exceção. Para obter mais informações sobre SQLGetData, consulte o SDK do Windows.

Exemplo

O código de exemplo a seguir ilustra chamadas de GetFieldValue para um objeto de conjunto de registros declarado diretamente de 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();

Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

CRecordset::GetODBCFieldCount

Recupera o número total de campos no objeto do conjunto de registros.

short GetODBCFieldCount() const;

Valor retornado

O número de campos no conjunto de registros.

Comentários

Para obter mais informações sobre como criar conjuntos de registros, consulte Conjunto de registros: criando e fechando conjunto de registros (ODBC).

CRecordset::GetODBCFieldInfo

Obtém informações sobre os campos no conjunto de registros.

void GetODBCFieldInfo(
    LPCTSTR lpszName,
    CODBCFieldInfo& fieldinfo);

void GetODBCFieldInfo(
    short nIndex,
    CODBCFieldInfo& fieldinfo);

Parâmetros

lpszName
O nome de um campo.

fieldinfo
Uma referência a uma estrutura CODBCFieldInfo.

nIndex
O índice de base zero do campo.

Comentários

Uma versão da função permite pesquisar um campo por nome. A outra versão permite pesquisar um campo pelo índice.

Para obter uma descrição sobre as informações retornadas, consulte a estrutura CODBCFieldInfo.

Para obter mais informações sobre como criar conjuntos de registros, consulte Conjunto de registros: criando e fechando conjunto de registros (ODBC).

CRecordset::GetRecordCount

Determina o tamanho do conjunto de registros.

long GetRecordCount() const;

Valor retornado

O número de registros no conjunto de registros; 0 se o conjunto de registros não contiver registros; ou -1 se não for possível determinar a contagem de registros.

Comentários

CRecordset::GetRowsetSize

Obtém a configuração atual para o número de linhas que você deseja recuperar durante uma determinada busca.

DWORD GetRowsetSize() const;

Valor retornado

O número de linhas a serem recuperadas durante uma determinada busca.

Comentários

Se você estiver usando a busca em massa de linhas, o tamanho padrão do conjunto de linhas quando o conjunto de registros for aberto será 25; caso contrário, será 1.

Para implementar a busca de linhas em massa, você deve especificar a opção CRecordset::useMultiRowFetch no parâmetro dwOptions da função de membro Open. Para alterar a configuração do tamanho do conjunto de linhas, chame SetRowsetSize.

Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

CRecordset::GetRowsFetched

Determina quantos registros foram recuperados após uma busca.

DWORD GetRowsFetched() const;

Valor retornado

O número de linhas recuperadas da fonte de dados após uma determinada busca.

Comentários

Isso é útil quando você implementa a busca de linhas em massa. O tamanho do conjunto de linhas normalmente indica quantas linhas serão recuperadas de uma busca. No entanto, o número total de linhas no conjunto de registros também afeta quantas linhas serão recuperadas em um conjunto de linhas. Por exemplo, se o conjunto de registros tiver 10 registros com uma configuração de tamanho de conjunto de linhas de quatro, o loop pelo conjunto de registros chamando MoveNext resultará no conjunto de linhas final com apenas dois registros.

Para implementar a busca de linhas em massa, você deve especificar a opção CRecordset::useMultiRowFetch no parâmetro dwOptions da função de membro Open. Para especificar o tamanho do conjunto de linhas, chame SetRowsetSize.

Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

Exemplo

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

Obtém o status de uma linha no conjunto de linhas atual.

WORD GetRowStatus(WORD wRow) const;

Parâmetros

wRow
A posição baseada em um de uma linha no conjunto de linhas atual. Esse valor pode variar de 1 até o tamanho do conjunto de linhas.

Valor retornado

Um valor de status para a linha. Para obter detalhes, consulte Observações.

Comentários

GetRowStatus retorna um valor que indica alguma alteração no status da linha desde a última recuperação da fonte de dados ou que nenhuma linha correspondente a wRow foi buscada. A tabela a seguir lista os possíveis valores de retorno.

Valor de status	Descrição
SQL_ROW_SUCCESS	A linha é inalterada.
SQL_ROW_UPDATED	A linha foi atualizada.
SQL_ROW_DELETED	A linha foi excluída.
SQL_ROW_ADDED	A linha foi adicionada.
SQL_ROW_ERROR	A linha não pode ser recuperada devido a um erro.
SQL_ROW_NOROW	Nenhuma linha corresponde a wRow.

Para obter mais informações, confira a função de API ODBC SQLExtendedFetch no SDK do Windows.

CRecordset::GetStatus

Determina o índice do registro atual no conjunto de registros e se o último registro foi visto.

void GetStatus(CRecordsetStatus& rStatus) const;

Parâmetros

rStatus
Uma referência a um objeto CRecordsetStatus. Para obter mais informações, consulte Comentários.

Comentários

CRecordset tenta controlar o índice, mas em algumas circunstâncias isso pode não ser possível. Consulte GetRecordCount para obter uma explicação.

A estrutura CRecordsetStatus tem a seguinte forma:

struct CRecordsetStatus
{
    long m_lCurrentRecord;
    BOOL m_bRecordCountFinal;
};

Os dois membros de CRecordsetStatus tẽm os seguintes significados:

• m_lCurrentRecord Contém o índice baseado em zero do registro atual no conjunto de registros, se for conhecido. Se não for possível determinar o índice, esse membro conterá AFX_CURRENT_RECORD_UNDEFINED (-2). Se IsBOF for TRUE (conjunto de registros vazio ou tentar se deslocar antes do primeiro registro), então m_lCurrentRecord será definido como AFX_CURRENT_RECORD_BOF (-1). Se estiver no primeiro registro, ele será definido como 0, no segundo registro será 1 e assim por diante.

• m_bRecordCountFinal Diferente de zero se o número total de registros no conjunto de registros tiver sido determinado. Geralmente, isso deve ser feito começando no início do conjunto de registros e chamando MoveNext até que IsEOF retorne diferente de zero. Se esse membro for zero, a contagem de registros conforme retornado por GetRecordCount, se não -1, é apenas uma contagem de "marca d'água alta" dos registros.

CRecordset::GetSQL

Chame essa função de membro para obter a instrução SQL que foi usada para selecionar os registros do conjunto de registros quando ele foi aberto.

const CString& GetSQL() const;

Valor retornado

Uma referência a const para um CString que contém a instrução SQL.

Comentários

Geralmente, essa será uma instrução SELECT do SQL. A cadeia de caracteres retornada por GetSQL é somente leitura.

Normalmente, a cadeia de caracteres retornada por GetSQL é diferente de qualquer cadeia de caracteres que você possa ter passado para o conjunto de registros no parâmetro lpszSQL para a função de membro Open. Isso ocorre porque o conjunto de registros constrói um instrução SQL completa baseada no que você passou para Open, no que você pode ter especificado com ClassWizard e no que você pode ter especificado nos membros de dados m_strFilter e m_strSort. Para obter detalhes sobre como o conjunto de registros constrói essa instrução SQL, consulte Conjunto de registros: como conjuntos de registros selecionam registros (ODBC).

CRecordset::GetTableName

Obtém o nome da tabela SQL na qual a consulta do conjunto de registros se baseia.

const CString& GetTableName() const;

Valor retornado

Uma referência a const para um CString que contém o nome da tabela, se o conjunto de registros for baseado em uma tabela; caso contrário, uma cadeia de caracteres vazia.

Comentários

GetTableName só será válido se o conjunto de registros for baseado em uma tabela, não uma junção de várias tabelas ou uma consulta predefinida (procedimento armazenado). O nome é somente leitura.

CRecordset::IsBOF

Retornará diferente de zero se o conjunto de registros tiver sido posicionado antes do primeiro registro. Não há registro atual.

BOOL IsBOF() const;

Valor retornado

Diferente de zero se o conjunto de registros não contiver registros ou se você tiver se deslocado para trás antes do primeiro registro; caso contrário, será 0.

Comentários

Chame essa função de membro antes de se deslocar de registro para registro para saber se foi até antes do primeiro registro do conjunto de registros. Você também pode usar IsBOF com IsEOF para determinar se o conjunto de registros contém registros ou se está vazio. Imediatamente após você chamar Open, se o conjunto de registros não contiver registros, IsBOF retornará diferente de zero. Quando você abre um conjunto de registros que tem pelo menos um registro, o primeiro registro é o registro atual e IsBOF retorna 0.

Se o primeiro registro for o registro atual e você chamar MovePrev, IsBOF retornará diferente de zero. Se IsBOF retornar diferente de zero e você chamar MovePrev, ocorrerá um erro. Se IsBOF retornar diferente de zero, o registro atual será indefinido e qualquer ação que exija um registro atual resultará em um erro.

Exemplo

Este exemplo usa IsBOF e IsEOF para detectar os limites de um conjunto de registros à medida que o código rola pelo conjunto de registros em ambas as direções.

// 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 o registro atual foi excluído.

BOOL IsDeleted() const;

Valor retornado

Diferente de zero se o conjunto de registros estiver posicionado em um registro excluído; caso contrário, será 0.

Comentários

Se você se deslocar para um registro e IsDeleted retornar TRUE (diferente de zero), você deverá mover para outro registro antes de executar qualquer outra operação de conjunto de registros.

O resultado depende de IsDeleted muitos fatores, como o tipo de conjunto de registros, se o conjunto de registros está atualizável, se você especificou a opção CRecordset::skipDeletedRecords quando abriu o conjunto de registros, se os pacotes de driver excluíram registros e se há vários usuários.

Para obter mais informações sobre CRecordset::skipDeletedRecords e empacotamento de drivers, consulte a função de membro Open.

CRecordset::IsEOF

Retornará diferente de zero se o conjunto de registros tiver sido posicionado depois do último registro. Não há registro atual.

BOOL IsEOF() const;

Valor retornado

Diferente de zero se o conjunto de registros não contiver registros ou se você tiver se deslocado para além do último registro; caso contrário, será 0.

Comentários

Chame essa função de membro quando você se deslocar de registro para registro para saber se você foi antes do último registro do conjunto de registros. Você também pode usar IsEOF para determinar se o conjunto de registros contém registros ou se está vazio. Imediatamente após você chamar Open, se o conjunto de registros não contiver registros, IsEOF retornará diferente de zero. Quando você abre um conjunto de registros que tem pelo menos um registro, o primeiro registro é o registro atual e IsEOF retorna 0.

Se o último registro for o registro atual e você chamar MoveNext, IsEOF retornará diferente de zero. Se IsEOF retornar diferente de zero e você chamar MoveNext, ocorrerá um erro. Se IsEOF retornar diferente de zero, o registro atual será indefinido e qualquer ação que exija um registro atual resultará em um erro.

Exemplo

Confira o exemplo de IsBOF.

CRecordset::IsFieldDirty

Determina se o membro de dados de campo especificado foi alterado desde que Edit ou AddNew foi chamado.

BOOL IsFieldDirty(void* pv);

Parâmetros

pv
Um ponteiro para o membro de dados de campo cujo status você deseja verificar ou NULL para determinar se algum dos campos está sujo.

Valor retornado

Diferente de zero se o membro de dados de campo especificado tiver sido alterado desde a chamada de AddNew ou Edit; caso contrário, 0.

Comentários

Os dados em todos os membros de dados de campo sujo serão transferidos para o registro na fonte de dados quando o registro atual for atualizado por uma chamada para a função membro Update de CRecordset (seguindo uma chamada para Edit ou AddNew).

A chamada IsFieldDirty redefinirá os efeitos das chamadas anteriores para SetFieldDirty, uma vez que o status sujo do campo é reavaliado. No caso de AddNew, se o valor do campo atual for diferente do valor pseudo nulo, o status do campo será definido como sujo. No caso de Edit, se o valor do campo for diferente do valor armazenado em cache, o status do campo será definido como sujo.

IsFieldDirty é implementado por meio de DoFieldExchange.

Para obter mais informações sobre o sinalizador sujo, consulte Conjunto de registros: como conjuntos de registros selecionam registros (ODBC).

CRecordset::IsFieldNull

Retornará diferente de zero se o campo especificado no registro atual for Null (sem valor).

BOOL IsFieldNull(void* pv);

Parâmetros

pv
Um ponteiro para o membro de dados de campo cujo status você deseja verificar ou NULL para determinar se algum dos campos é Null.

Valor retornado

Diferente de zero se o membro de dados de campo especificado estiver sinalizado como Null; caso contrário, será 0.

Comentários

Chame essa função de membro para determinar se o membro de dados de campo especificado de um dynaset foi sinalizado como "sujo" (alterado). (Na terminologia do banco de dados, Null significa "sem valor" e não é o mesmo que NULL em C++.) Se um membro de dados de campo for sinalizado como Null, ele será interpretado como uma coluna do registro atual para o qual não há valor.

IsFieldNull é implementado por meio de DoFieldExchange.

CRecordset::IsFieldNullable

Retornará diferente de zero se o campo especificado no registro atual puder ser definido como nulo (sem valor).

BOOL IsFieldNullable(void* pv);

Parâmetros

pv
Um ponteiro para o membro de dados de campo cujo status você deseja verificar ou NULL para determinar se algum dos campos pode ser definido par aum valor Null.

Comentários

Chame essa função de membro para determinar se o membro de dados de campo especificado é "anulável" (pode ser definido como um valor Null; O NULL do C++ não é o mesmo que Null, o que, na terminologia do banco de dados, significa "sem valor").

Um campo que não pode ser Null deve ter um valor. Se você tentar definir esse campo como Null ao adicionar ou atualizar um registro, a fonte de dados rejeitará a adição ou atualização e Update lançará uma exceção. A exceção ocorre quando você chama Update, não quando você chama SetFieldNull.

O uso de NULL para o primeiro argumento da função aplicará a função somente aos campos outputColumn, não campos a param. Por exemplo, a chamada

SetFieldNull(NULL);

definirá apenas campos outputColumn como NULL; campos param não serão afetados.

Para trabalhar em campos param, você deve fornecer o endereço real do param individual no qual deseja trabalhar, como:

SetFieldNull(&m_strParam);

Isso significa que você não pode definir todos os campos param para NULL, como você pode com campos outputColumn.

IsFieldNullable é implementado por meio de DoFieldExchange.

CRecordset::IsOpen

Determina se o conjunto de registros já está aberto.

BOOL IsOpen() const;

Valor retornado

Diferente de zero se a função do membro Open ou Requery do objeto do conjunto de registros tiver sido chamada anteriormente e o conjunto de registros não tiver sido fechado; caso contrário, será 0.

CRecordset::m_hstmt

Contém um identificador para a estrutura de dados da instrução ODBC, do tipo HSTMT, associada ao conjunto de registros.

Comentários

Cada consulta a uma fonte de dados ODBC está associada a um HSTMT.

Normalmente, você não precisa acessar o HSTMT diretamente, mas talvez seja necessário para execução direta de instruções SQL. A função de membro ExecuteSQL da classe CDatabase fornece um exemplo do uso de m_hstmt.

CRecordset::m_nFields

Contém o número de membros de dados de campo na classe de conjunto de registros; ou seja, o número de colunas selecionadas pelo conjunto de registros da fonte de dados.

Comentários

O construtor da classe do conjunto de registros deve inicializar m_nFields com o número correto. Se você ainda não implementou a busca em massa de linhas, ClassWizard grava essa inicialização para você ao usá-la para declarar sua classe de conjunto de registros. Você também pode gravá-lo manualmente.

A estrutura usa esse número para gerenciar a interação entre os membros dos dados de campo e as colunas correspondentes do registro atual na fonte de dados.

Você pode associar colunas dinamicamente, conforme explicado no artigo "Recordset: Dynamically Binding Data Columns". Se você fizer isso, deverá aumentar a contagem em m_nFields para refletir o número de chamadas de função RFX ou RFX em massa em sua função de membro DoFieldExchange ou DoBulkFieldExchange para as colunas associadas dinamicamente.

Para obter mais informações, consulte os artigos Conjunto de registros: Associação dinâmica de colunas de dados (ODBC) e Conjunto de registros: buscando registros em massa (ODBC).

Exemplo

confira Registrar troca de campos: usando RFX.

CRecordset::m_nParams

Contém o número de membros de dados de parâmetro na classe de conjunto de registros; ou seja, o número de parâmetros passados com a consulta do conjunto de registros.

Comentários

Se a classe do conjunto de registros tiver membros de dados de parâmetro, o construtor da classe deverá inicializar m_nParams com o número correto. O valor padrão de m_nParams é 0. Se você adicionar membros de dados de parâmetro, o que você deve fazer manualmente, também deve adicionar manualmente uma inicialização no construtor de classe para refletir o número de parâmetros (que devem ser pelo menos tão grandes quanto o número de espaços reservados '' em sua cadeia de caracteres m_strFilter ou m_strSort).

A estrutura usa esse número quando parametriza a consulta do conjunto de registros.

Exemplo

Consulte os artigos Conjunto de registros: Parametrizando um conjunto de registros (ODBC) e Troca de campos de registro: usando RFX.

CRecordset::m_pDatabase

Contém um ponteiro para o objeto CDatabase por meio do qual o conjunto de registros está conectado a uma fonte de dados.

Comentários

Essa variável é definida de duas maneiras. Normalmente, você passa um ponteiro para um objeto CDatabase já conectado ao construir o objeto do conjunto de registros. Se você passar NULL em vez disso, CRecordset cria um objeto CDatabase para você e o conecta. Em ambos os casos, CRecordset armazena o ponteiro nessa variável.

Normalmente, você não precisará usar o ponteiro armazenado em m_pDatabase diretamente. No entanto, se você escrever suas próprias extensões para CRecordset, talvez seja necessário usar o ponteiro. Por exemplo, talvez você precise do ponteiro se lançar seus próprios CDBExceptions. Ou talvez você precise dele se tiver que fazer algo usando o mesmo objeto CDatabase, como executar transações, definir tempos limite ou chamar a função de membro ExecuteSQL da classe CDatabase para executar instruções SQL diretamente.

CRecordset::m_strFilter

Depois de construir o objeto do conjunto de registros, mas antes de chamar sua função de membro Open, use esse membro de dados para armazenar um CString que contém uma cláusula WHERE SQL.

Comentários

O conjunto de registros usa essa cadeia de caracteres para restringir (ou filtrar) os registros selecionados durante a chamada de Open ou Requery. Isso é útil para selecionar um subconjunto de registros, como "todos os vendedores com sede na Califórnia" ("state = CA"). A sintaxe do SQL ODBC para uma cláusula WHERE é

WHERE search-condition

Não inclua a palavra-chave WHERE na cadeia de caracteres. A estrutura a fornece.

Você também pode parametrizar sua cadeia de caracteres de filtro colocando espaços reservados '' nele, declarando um membro de dados de parâmetro em sua classe para cada espaço reservado e passando parâmetros para o conjunto de registros em tempo de execução. Isso permite que você construa o filtro no tempo de execução. Para obter mais informações, confira Conjunto de registros: parametrizando um conjunto de registros (ODBC).

Para obter mais informações sobre cláusulas WHERE SQL, consulte SQL. Para obter mais informações sobre como selecionar e filtrar registros, consulte Conjunto de registros: filtrando registros (ODBC).

Exemplo

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

Depois de construir o objeto do conjunto de registros, mas antes de chamar sua função de membro Open, use esse membro de dados para armazenar um CString que contém uma cláusula ORDER BY SQL.

Comentários

O conjunto de registros usa essa cadeia de caracteres para classificar os registros selecionados durante a chamada de Open ou Requery. Você pode usar esse recurso para classificar um conjunto de registros em uma ou mais colunas. A sintaxe do SQL ODBC para uma cláusula ORDER BY fica

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

onde uma especificação de classificação é um inteiro ou um nome de coluna. Você também pode especificar a ordem crescente ou decrescente (a ordem é crescente por padrão) acrescentando "ASC" ou "DESC" à lista de colunas na cadeia de caracteres de classificação. Os registros selecionados são classificados primeiro pela primeira coluna listada, depois pela segunda e assim por diante. Por exemplo, você pode solicitar um conjunto de registros "Clientes" pelo sobrenome e, em seguida, primeiro nome. O número de colunas que você pode listar depende da fonte de dados. Para obter mais informações, confira o SDK do Windows.

Não inclua a palavra-chave ORDER BY na cadeia de caracteres. A estrutura a fornece.

Para obter mais informações sobre cláusulas SQL, consulte SQL. Para obter mais informações sobre como classificar registros, consulte Conjunto de registros: Classificando registros (ODBC).

Exemplo

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

Move o ponteiro do registro atual dentro do conjunto de registros, seja para frente ou para trás.

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

Parâmetros

nRows
O número de linhas a serem movidas para frente ou para trás. Os valores positivos avançam até o final do conjunto de registros. Valores negativos se movem para trás, em direção ao início.

wFetchType
Determina o conjunto de linhas que Move buscará. Para obter detalhes, consulte Observações.

Comentários

Se você passar um valor de 0 para nRows, Move atualizará o registro atual; Move encerrará qualquer modo AddNew ou Edit atual e restaurará o valor do registro atual antes de AddNew ou Edit ter sido chamado.

Move reposiciona o conjunto de registros por conjuntos de linhas. Com base nos valores para nRows e wFetchType, Move busca o conjunto de linhas apropriado e, em seguida, faz o primeiro registro nesse conjunto de linhas o registro atual. Se você ainda não implementou a busca de linhas em massa, o tamanho do conjunto de linhas será sempre 1. Ao buscar um conjunto de linhas, Move chama diretamente a função de membro CheckRowsetError para lidar com os erros resultantes da busca.

Dependendo dos valores que você passa, Move é equivalente a outras funções de membro CRecordset. Em particular, o valor de wFetchType pode indicar uma função membro mais intuitiva e geralmente o método preferencial para mover o registro atual.

A tabela a seguir lista os valores possíveis para wFetchType, o conjunto de linhas que Move buscará com base em wFetchType e nRows, e qualquer função de membro equivalente correspondente a wFetchType.

wFetchType	Conjunto de linhas buscado	Função de membro equivalente
SQL_FETCH_RELATIVE (o valor padrão)	O conjunto de linhas iniciando nRows linha(s) a partir da primeira linha no conjunto de linhas atual.
SQL_FETCH_NEXT	O próximo conjunto de linhas; nRows é ignorado.	MoveNext
SQL_FETCH_PRIOR	O conjunto de linhas anterior; nRows é ignorado.	MovePrev
SQL_FETCH_FIRST	O primeiro conjunto de linhas no conjunto de registros; nRows é ignorado.	MoveFirst
SQL_FETCH_LAST	O último conjunto de linhas completo no conjunto de registros; nRows é ignorado.	MoveLast
SQL_FETCH_ABSOLUTE	Se nRows> 0, o conjunto de linhas iniciando nRows linha(s) a partir do início do conjunto de registros. Se nRows< 0, o conjunto de linhas iniciando nRows linha(s) a partir do final do conjunto de registros. Se nRows = 0, uma condição BOF (início do arquivo) será retornada.	SetAbsolutePosition
SQL_FETCH_BOOKMARK	O conjunto de linhas que começa na linha cujo valor de indicador corresponde a nRows.	SetBookmark

Para obter mais informações sobre a navegação em conjunto de registros, confira o artigo Conjunto de registros: deslocamento (ODBC) e Conjunto de registros: Indicadores e posições absolutas (ODBC). Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC). Para obter informações relacionadas, confira a função de API ODBC SQLExtendedFetch no SDK do Windows.

Exemplo

// 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

Faz do primeiro registro no primeiro conjunto de linhas o registro atual.

void MoveFirst();

Comentários

Independentemente de a busca em massa de linhas ter sido implementada, esse sempre será o primeiro registro no conjunto de registros.

Você não precisa chamar MoveFirst imediatamente depois de abrir o conjunto de registros. Nesse momento, o primeiro registro (se houver) é automaticamente o registro atual.

Para obter mais informações sobre a navegação em conjunto de registros, confira o artigo Conjunto de registros: deslocamento (ODBC) e Conjunto de registros: Indicadores e posições absolutas (ODBC). Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

Exemplo

Confira o exemplo de IsBOF.

CRecordset::MoveLast

Faz com que o primeiro registro no último conjunto de linhas completo seja o registro atual.

void MoveLast();

Comentários

Se você não tiver implementado a busca em linha em massa, o conjunto de registros terá um tamanho de conjunto de linhas de 1, portanto, MoveLast passará para o último registro no conjunto de registros.

Para obter mais informações sobre a navegação em conjunto de registros, confira o artigo Conjunto de registros: deslocamento (ODBC) e Conjunto de registros: Indicadores e posições absolutas (ODBC). Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

Exemplo

Confira o exemplo de IsBOF.

CRecordset::MoveNext

Faz do primeiro registro no próximo conjunto de linhas o registro atual.

void MoveNext();

Comentários

Se você não tiver implementado a busca em linha em massa, o conjunto de registros terá um tamanho de conjunto de linhas de 1, portanto, MoveNext passará para o próximo registro.

Para obter mais informações sobre a navegação em conjunto de registros, confira o artigo Conjunto de registros: deslocamento (ODBC) e Conjunto de registros: Indicadores e posições absolutas (ODBC). Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

Exemplo

Confira o exemplo de IsBOF.

CRecordset::MovePrev

Faz do primeiro registro no conjunto de linhas anterior o registro atual.

void MovePrev();

Comentários

Se você não tiver implementado a busca em linha em massa, o conjunto de registros terá um tamanho de conjunto de linhas de 1, portanto, MovePrev passará para o próximo registro.

Para obter mais informações sobre a navegação em conjunto de registros, confira o artigo Conjunto de registros: deslocamento (ODBC) e Conjunto de registros: Indicadores e posições absolutas (ODBC). Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

Exemplo

Confira o exemplo de IsBOF.

CRecordset::OnSetOptions

Chamado para definir opções (usadas na seleção) para a instrução ODBC especificada.

virtual void OnSetOptions(HSTMT hstmt);

Parâmetros

hstmt
O HSTMT da instrução ODBC cujas opções devem ser definidas.

Comentários

Chame OnSetOptions para definir opções (usadas na seleção) para a instrução ODBC especificada. A estrutura chama essa função membro para definir opções iniciais para o conjunto de registros. OnSetOptions determina o suporte da fonte de dados para cursores roláveis e para simultaneidade do cursor e define as opções do conjunto de registros de acordo. (Enquanto OnSetOptions é usado para operações de seleção, OnSetUpdateOptions é usado para operações de atualização.)

Substitua OnSetOptions para definir opções específicas para o driver ou a fonte de dados. Por exemplo, se a fonte de dados der suporte à abertura para acesso exclusivo, você poderá substituir OnSetOptions para aproveitar essa capacidade.

Para obter mais informações sobre cursores, consulte ODBC.

CRecordset::OnSetUpdateOptions

Chamado para definir opções (usadas na atualização) para a instrução ODBC especificada.

virtual void OnSetUpdateOptions(HSTMT hstmt);

Parâmetros

hstmt
O HSTMT da instrução ODBC cujas opções devem ser definidas.

Comentários

Chame OnSetUpdateOptions para definir opções (usadas na atualização) para a instrução ODBC especificada. A estrutura chama essa função de membro depois de criar um HSTMT para atualizar registros em um conjunto de registros. (Enquanto OnSetOptions é usado para operações de seleção, OnSetUpdateOptions é usado para operações de atualização.) OnSetUpdateOptions determina o suporte da fonte de dados para cursores roláveis e para simultaneidade do cursor e define as opções do conjunto de registros adequadamente.

Substitua OnSetUpdateOptions para definir opções de uma instrução ODBC antes que essa instrução seja usada para acessar um banco de dados.

Para obter mais informações sobre cursores, consulte ODBC.

CRecordset::Open

Abre o conjunto de registros recuperando a tabela ou executando a consulta que o conjunto de registros representa.

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

Parâmetros

nOpenType
Aceite o valor padrão, AFX_DB_USE_DEFAULT_TYPE, ou use um dos seguintes valores do enum OpenType:

• CRecordset::dynaset Um conjunto de registros com deslocamento bidirecional. Abrir o conjunto de registros determina a associação e a ordenação dos registros, mas as alterações feitas por outros usuários aos valores de dados ficam visíveis após uma operação de busca. Os dynasets também são conhecidos como conjuntos de registros controlados por conjuntos de chaves.

• CRecordset::snapshot Um conjunto de registros estático com deslocamento bidirecional. Abrir o conjunto de registros determina a associação e a ordenação dos registros. Buscar um registro determina os valores de dados. As alterações feitas por outros usuários não ficam visíveis até que o conjunto de registros seja fechado e reaberto.

• CRecordset::dynamic Um conjunto de registros com deslocamento bidirecional. As alterações feitas por outros usuários aos valores de associação, ordenação e dados ficam visíveis após uma operação de busca. Muitos drivers ODBC não dão suporte a esse tipo de conjunto de registros.

• CRecordset::forwardOnly Um conjunto de registros somente leitura com somente rolagem para a frente.

  Para CRecordset, o valor padrão e CRecordset::snapshot. O mecanismo de valor padrão permite que os assistentes do Visual C++ interajam com ODBC CRecordset e DAO CDaoRecordset, que têm padrões diferentes.

Para obter mais informações sobre esses tipos de conjunto de registros, consulte Conjunto de registros (ODBC). Para obter informações relacionadas, consulte "Usando cursores de bloco e rolável" no SDK do Windows.

lpszSQL
Um ponteiro de cadeia de caracteres que contém um dos seguintes:

• Um ponteiro NULL.

• O nome de uma tabela.

• Uma instrução SQL SELECT (opcionalmente com uma cláusula SQL WHERE ou ORDER BY).

• Uma instrução CALL que especifica o nome de uma consulta predefinida (procedimento armazenado). Tenha cuidado para não inserir espaço em branco entre a chave e a palavra-chave CALL.

Para obter mais informações sobre essa cadeia de caracteres, consulte a tabela e a discussão da função de ClassWizard na seção Comentários.

dwOptions
Uma máscara de bits, que pode especificar uma combinação dos valores listados abaixo. Alguns deles são mutualmente exclusivos. O valor padrão é none.

• CRecordset::none Nenhuma opção definida. Esse valor de parâmetro é mutuamente exclusivo com todos os outros valores. Por padrão, o conjunto de registros pode ser atualizado com Edit ou Delete e permite acrescentar novos registros com AddNew. A capacidade de atualização depende da fonte de dados e da opção nOpenType especificada. A otimização para adições em massa não está disponível. A busca em massa de linhas não será implementada. Os registros excluídos não serão ignorados durante a navegação do conjunto de registros. Indicadores não estão disponíveis. A verificação automática de campo sujo é implementada.

• CRecordset::appendOnly Não permita Edit ou Delete no conjunto de registros. Permita somente AddNew. Essa opção é mutualmente exclusiva com CRecordset::readOnly.

• CRecordset::readOnly Abra o conjunto de registros como somente leitura. Essa opção é mutualmente exclusiva com CRecordset::appendOnly.

• CRecordset::optimizeBulkAdd Use uma instrução SQL preparada para otimizar a adição de muitos registros ao mesmo tempo. Aplica-se somente se você não estiver usando a função de API ODBC SQLSetPos para atualizar o conjunto de registros. A primeira atualização determina quais campos estão marcados como sujos. Essa opção é mutualmente exclusiva com CRecordset::useMultiRowFetch.

• CRecordset::useMultiRowFetch Implemente a busca de linha em massa para permitir que várias linhas sejam recuperadas em uma única operação de busca. Esse é um recurso avançado projetado para melhorar o desempenho; no entanto, a troca de campo de registro em massa não é compatível com ClassWizard. Essa opção é mutualmente exclusiva com CRecordset::optimizeBulkAdd. Se você especificar CRecordset::useMultiRowFetch, a opção CRecordset::noDirtyFieldCheck será ativada automaticamente (buffer duplo não estará disponível); em conjuntos de registros somente encaminhamento, a opção CRecordset::useExtendedFetch será ativada automaticamente. Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

• CRecordset::skipDeletedRecords Ignore todos os registros excluídos ao navegar pelo conjunto de registros. Isso diminuirá o desempenho em determinadas buscas relativas. Essa opção não é válida em conjuntos de registros que sejam somente encaminhamento. Se você chamar Move com o parâmetro nRows definido como 0 e o conjunto de opções CRecordset::skipDeletedRecords, Move confirmará. CRecordset::skipDeletedRecords é semelhante ao empacotamento de driver, o que significa que as linhas excluídas são removidas do conjunto de registros. No entanto, se o driver empacotar registros, ele ignorará apenas os registros que você excluir; ele não ignorará os registros excluídos por outros usuários enquanto o conjunto de registros estiver aberto. CRecordset::skipDeletedRecords ignorará as linhas excluídas por outros usuários.

• CRecordset::useBookmarks Pode usar indicadores no conjunto de registros, se houver suporte. Indicadores reduzem a recuperação de dados, mas melhoram o desempenho para navegação de dados. Não é válido em conjuntos de registros que sejam somente encaminhamento. Para obter mais informações, confira Conjunto de registros: indicadores e posições absolutas (ODBC).

• CRecordset::noDirtyFieldCheck Desative a verificação automática de campo sujo (buffer duplo). Isso melhorará o desempenho; no entanto, você deve marcar manualmente campos como sujos chamando as funções de membro SetFieldDirty e SetFieldNull. O buffer duplo na classe CRecordset é semelhante ao buffer duplo na classe CDaoRecordset. No entanto, em CRecordset, você não pode habilitar o buffer duplo em campos individuais; habilitá-lo para todos os campos ou desabilitá-lo para todos os campos. Se você especificar a opção CRecordset::useMultiRowFetch, CRecordset::noDirtyFieldCheck será ativado automaticamente; no entanto, SetFieldDirty e SetFieldNull não podem ser usados em conjuntos de registros que implementam a busca de linha em massa.

• CRecordset::executeDirect Não use uma instrução SQL preparada. Para melhorar o desempenho, especifique essa opção se a função de membro Requery nunca for chamada.

• CRecordset::useExtendedFetch Implemente SQLExtendedFetch em vez de SQLFetch. Isso foi projetado para implementar a busca de linhas em massa em conjuntos de registros que sejam somente encaminhamento. Se você especificar a opção CRecordset::useMultiRowFetch em um conjunto de registros somente encaminhamento, CRecordset::useExtendedFetch será ativado automaticamente.

• CRecordset::userAllocMultiRowBuffers O usuário alocará buffers de armazenamento para os dados. Use essa opção com CRecordset::useMultiRowFetch se quiser alocar seu próprio armazenamento. Caso contrário, a estrutura alocará automaticamente o armazenamento necessário. Para obter mais informações, confira Conjunto de registros: buscando registros em massa (ODBC). Especificar CRecordset::userAllocMultiRowBuffers sem especificar CRecordset::useMultiRowFetch resulta em uma declaração com falha.

Valor retornado

Diferente de zero se o objeto CRecordset foi aberto com êxito; caso contrário, 0 se CDatabase::Open (se chamado) retornar 0.

Comentários

Você deve chamar essa função de membro para executar a consulta definida pelo conjunto de registros. Antes de chamar Open, você deve construir o objeto do conjunto de registros.

A conexão desse conjunto de registros com a fonte de dados depende de como você constrói o conjunto de registros antes de chamar Open. Se você passar um objeto CDatabase para o construtor do conjunto de registros que não foi conectado à fonte de dados, essa função de membro usará GetDefaultConnect para tentar abrir o objeto de banco de dados. Se você passar NULL para o construtor do conjunto de registros, o construtor construirá um objeto CDatabase para você e Open tentará conectar o objeto de banco de dados. Para obter detalhes sobre como fechar o conjunto de registros e a conexão nessas circunstâncias variadas, confira Close.

Quando você chama Open, uma consulta, geralmente uma instrução SQL SELECT, seleciona registros com base nos critérios mostrados na tabela a seguir.

Valor do parâmetro lpszSQL	Os registros selecionados são determinados por	Exemplo
NULL	Cadeia de caracteres retornada por GetDefaultSQL.
Nome da tabela SQL	Todas as colunas da lista de tabelas em DoFieldExchange ou DoBulkFieldExchange.	"Customer"
Nome da consulta predefinida (procedimento armazenado)	As colunas que a consulta está definida para retornar.	"{call OverDueAccts}"
lista de tabelas FROM da lista de colunas SELECT	As colunas especificadas das tabelas especificadas.	"SELECT CustId, CustName FROM Customer"

O procedimento usual é passar NULL para Open; nesse caso, Open chama GetDefaultSQL. Se você estiver usando uma classe CRecordset derivada, GetDefaultSQL fornecerá os nomes de tabela especificados em ClassWizard. Em vez disso, você pode especificar outras informações no parâmetro lpszSQL.

Independentemente do que você passar, Open constrói uma cadeia de caracteres SQL final para a consulta (a cadeia de caracteres pode ter cláusulas SQL WHERE e ORDER BY acrescentadas à cadeia de caracteres lpszSQL que você passou) e, em seguida, executa a consulta. Você pode examinar a cadeia de caracteres construída chamando GetSQL depois de chamar Open. Para obter mais detalhes sobre como o conjunto de registros constrói uma instrução SQL e seleciona registros, consulte Conjunto de registros: Como conjuntos de registros selecionam registros (ODBC).

Os membros de dados de campo da classe de conjunto de registros são associados às colunas dos dados selecionados. Se algum registro for retornado, o primeiro registro se tornará o registro atual.

Se você quiser definir opções para o conjunto de registros, como um filtro ou uma classificação, especifique-os depois de construir o objeto do conjunto de registros, mas antes de chamar Open. Se você quiser atualizar os registros no conjunto de registros depois que o conjunto de registros já estiver aberto, chame Requery.

Para obter mais informações, incluindo mais exemplos, consulte Conjunto de registros (ODBC),Conjunto de registros: Como conjuntos de registros selecionam registros (ODBC) e Conjunto de registros: Criando e fechando conjuntos de registros (ODBC).

Exemplo

Os exemplos de código a seguir mostram diferentes formas da chamada Open.

// 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

Atualizações os dados e o status de uma linha no conjunto de linhas atual.

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

Parâmetros

wRow
A posição baseada em um de uma linha no conjunto de linhas atual. Esse valor pode variar de 1 até o tamanho do conjunto de linhas.

wLockType
Um valor que indica como bloquear a linha após a atualização. Para obter detalhes, consulte Observações.

Comentários

Se você passar um valor de zero para wRow, cada linha no conjunto de linhas será atualizada.

Para usar RefreshRowset, você deve ter implementado a busca de linhas em massa especificando a opção CRecordset::useMulitRowFetch na função de membro Open.

RefreshRowset chama a função de API ODBC SQLSetPos. O parâmetro wLockType especifica o estado de bloqueio da linha após a execução de SQLSetPos. A tabela a seguir descreve os valores possíveis de wLockType.

wLockType	Descrição
SQL_LOCK_NO_CHANGE (o valor padrão)	O driver ou a fonte de dados garante que a linha esteja no mesmo estado bloqueado ou desbloqueado como era antes de RefreshRowset ser chamado.
SQL_LOCK_EXCLUSIVE	O driver ou a fonte de dados bloqueia a linha exclusivamente. Nem todas as fontes de dados suportam esse tipo de bloqueio.
SQL_LOCK_UNLOCK	O driver ou a fonte de dados desbloqueia a linha. Nem todas as fontes de dados suportam esse tipo de bloqueio.

Para obter mais informações sobre SQLSetPos, consulte o SDK do Windows. Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

CRecordset::Requery

Recompila (atualiza) um conjunto de registros.

virtual BOOL Requery();

Valor retornado

Diferente de zero se o conjunto de registros foi recriado com êxito; caso contrário, 0.

Comentários

Se algum registro for retornado, o primeiro registro se tornará o registro atual.

Para que o conjunto de registros reflita as adições e exclusões que você ou outros usuários estão fazendo à fonte de dados, você deve recompilar o conjunto de registros chamando Requery. Se o conjunto de registros for um dynaset, ele refletirá automaticamente as atualizações que você ou outros usuários fazem em seus registros existentes (mas não adições). Se o conjunto de registros for um instantâneo, você deverá chamar Requery para refletir edições de outros usuários, além de adições e exclusões.

Para um dynaset ou um snapshot, chame Requery sempre que quiser recompilar o conjunto de registros usando um novo filtro ou classificação, ou valores de parâmetro. Defina o novo filtro ou propriedade de classificação atribuindo novos valores para m_strFilter e m_strSort antes de chamar Requery. Defina novos parâmetros atribuindo novos valores a membros de dados de parâmetro antes de chamar Requery. Se as cadeias de caracteres de filtro e classificação não forem alteradas, você poderá reutilizar a consulta, o que melhora o desempenho.

Se a tentativa de recompilar o conjunto de registros falhar, o conjunto de registros será fechado. Antes de chamar Requery, você pode determinar se o conjunto de registros pode ser requerido chamando a função de membro CanRestart. CanRestart não garante que Requery terá êxito.

Exemplo

Este exemplo recompila um conjunto de registros para aplicar uma ordem de classificação diferente.

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

Posiciona o conjunto de registros no registro correspondente ao número de registro especificado.

void SetAbsolutePosition(long nRows);

Parâmetros

nRows
A posição ordinal baseada em um para o registro atual no conjunto de registros.

Comentários

SetAbsolutePosition move o ponteiro de registro atual com base nessa posição ordinal.

Para conjuntos de registros ODBC, uma configuração de posição absoluta de 1 refere-se ao primeiro registro no conjunto de registros; uma configuração de 0 refere-se à posição de INÍCIO do arquivo (BOF).

Você também pode passar valores negativos para SetAbsolutePosition. Nesse caso, a posição do conjunto de registros é avaliada do final do conjunto de registros. Por exemplo, SetAbsolutePosition( -1 ) move o ponteiro de registro atual para o último registro no conjunto de registros.

Para obter mais informações sobre navegação de conjunto de registros e indicadores, consulte os artigos Conjunto de registros: Deslocamento (ODBC) e Conjunto de registros: Indicadores e posições absolutas (ODBC).

CRecordset::SetBookmark

Posiciona o conjunto de registros no registro que contém o indicador especificado.

void SetBookmark(const CDBVariant& varBookmark);

Parâmetros

varBookmark
Uma referência a um objeto CDBVariant que contém o valor do indicador para um registro específico.

Comentários

Para determinar se há suporte para indicadores no conjunto de registros, chame CanBookmark. Para disponibilizar indicadores se eles tiverem suporte, você deve definir a opção CRecordset::useBookmarks no parâmetro dwOptions da função de membro Open.

Para primeiro recuperar o indicador do registro atual, chame GetBookmark, que salva o valor do indicador em um objeto CDBVariant. Depois, você pode retornar a esse registro chamando SetBookmark usando o valor do indicador salvo.

Para obter mais informações sobre indicadores e navegação de conjunto de registros, consulte os artigos Conjunto de registros: indicadores e posições absolutas (ODBC) e Conjunto de registros: deslocamento (ODBC).

CRecordset::SetFieldDirty

Sinaliza um membro de dados de campo do conjunto de registros como alterado ou inalterado.

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

Parâmetros

pv
Contém o endereço de um membro de dados de campo no conjunto de registros ou NULL. Se for NULL, todos os membros de dados de campo no conjunto de registros serão sinalizados. (O NULL do C++ não é o mesmo que Null na terminologia do banco de dados, o que significa "sem valor".)

bDirty
TRUE se o membro de dados de campo deve ser sinalizado como "sujo" (alterado). Caso contrário, FALSE se o membro de dados de campo for sinalizado como "limpo" (inalterado).

Comentários

Marcar campos como inalterados garante que o campo não seja atualizado e resulte em menos tráfego SQL.

A estrutura marca os membros de dados de campo alterados para garantir que eles serão gravados no registro na fonte de dados pelo mecanismo RFX (troca de campo de registro). Alterar o valor de um campo geralmente define o campo sujo automaticamente, portanto, você raramente precisará chamar SetFieldDirty por conta própria, mas às vezes você pode querer garantir que as colunas sejam explicitamente atualizadas ou inseridas independentemente do valor no membro de dados de campo.

O uso de NULL para o primeiro argumento da função aplicará a função somente aos campos outputColumn, não campos a param. Por exemplo, a chamada

SetFieldNull(NULL);

definirá apenas campos outputColumn como NULL; campos param não serão afetados.

Para trabalhar em campos param, você deve fornecer o endereço real do param individual no qual deseja trabalhar, como:

SetFieldNull(&m_strParam);

Isso significa que você não pode definir todos os campos param para NULL, como você pode com campos outputColumn.

CRecordset::SetFieldNull

Sinaliza um membro de dados de campo do conjunto de registros como Null (especificamente sem valor) ou como não Null.

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

Parâmetros

pv
Contém o endereço de um membro de dados de campo no conjunto de registros ou NULL. Se for NULL, todos os membros de dados de campo no conjunto de registros serão sinalizados. (O NULL do C++ não é o mesmo que Null na terminologia do banco de dados, o que significa "sem valor".)

bNull
Diferente zero se o for preciso sinalizar o membro de dados do campo como sem valor (Null). Caso contrário, 0 se o membro de dados de campo for sinalizado como não nulo.

Comentários

Quando você adiciona um novo registro a um conjunto de registros, todos os membros de dados de campo são inicialmente definidos como um valor nulo e sinalizados como "sujos" (alterados). Quando você recupera um registro de uma fonte de dados, suas colunas já têm valores ou são nulas.

Se você quiser designar especificamente um campo do registro atual como não tendo um valor, chame SetFieldNull com bNull definido como TRUE para sinalizar como Null. Se um campo tiver sido marcado anteriormente como Nulo e você quiser dar a ele um valor, defina seu novo valor. Você não precisa remover o sinalizador Null com SetFieldNull. Para determinar se o campo tem permissão para ser nulo, chame IsFieldNullable.

O uso de NULL para o primeiro argumento da função aplicará a função somente aos campos outputColumn, não campos a param. Por exemplo, a chamada

SetFieldNull(NULL);

definirá apenas campos outputColumn como NULL; campos param não serão afetados.

Para trabalhar em campos param, você deve fornecer o endereço real do param individual no qual deseja trabalhar, como:

SetFieldNull(&m_strParam);

Isso significa que você não pode definir todos os campos param para NULL, como você pode com campos outputColumn.

SetFieldNull é implementado por meio de DoFieldExchange.

CRecordset::SetLockingMode

Define o modo de bloqueio como bloqueio "otimista" (o padrão) ou bloqueio "pessimista". Determina como os registros são bloqueados para atualizações.

void SetLockingMode(UINT nMode);

Parâmetros

nMode
Contém um dos seguintes valores do enum LockMode:

• optimistic O bloqueio otimista bloqueia o registro que está sendo atualizado somente durante a chamada para Update.

• pessimistic O bloqueio pessimista bloqueia o registro assim que Edit é chamado e o mantém bloqueado até que a chamada Update seja concluída ou você passe para um novo registro.

Comentários

Chame essa função de membro se você precisar especificar qual das duas estratégias de bloqueio de registro que o conjunto de registros está usando para atualizações. Por padrão, o modo de bloqueio de um conjunto de registros é optimistic. Você pode alterar isso para uma estratégia de bloqueio pessimistic mais cautelosa. Chame SetLockingMode depois de construir e abrir o objeto do conjunto de registros, mas antes de chamar Edit.

CRecordset::SetParamNull

Sinaliza um parâmetro como Null (especificamente sem valor) ou como não Null.

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

Parâmetros

nIndex
O índice baseado em zero do parâmetro.

bNull
Se for TRUE (o valor padrão), o parâmetro será sinalizado como Null. Caso contrário, o parâmetro será sinalizado como não Null.

Comentários

Diferentemente de SetFieldNull, você pode chamar SetParamNull antes de abrir o conjunto de registros.

SetParamNull normalmente é usado com consultas predefinidas (procedimentos armazenados).

CRecordset::SetRowsetCursorPosition

Move o cursor para uma linha dentro do conjunto de linhas atual.

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

Parâmetros

wRow
A posição baseada em um de uma linha no conjunto de linhas atual. Esse valor pode variar de 1 até o tamanho do conjunto de linhas.

wLockType
Valor que indica como bloquear a linha após a atualização. Para obter detalhes, consulte Observações.

Comentários

Ao implementar a busca de linhas em massa, os registros são recuperados por conjuntos de linhas, em que o primeiro registro no conjunto de linhas buscado é o registro atual. Para fazer outro registro dentro do conjunto de linhas do registro atual, chame SetRowsetCursorPosition. Por exemplo, você pode combinar SetRowsetCursorPosition com a função de membro GetFieldValue para recuperar dinamicamente os dados de qualquer registro do conjunto de registros.

Para usar SetRowsetCursorPosition, você deve ter implementado a busca de linhas em massa especificando a opção CRecordset::useMultiRowFetch do parâmetro dwOptions na função de membro Open.

SetRowsetCursorPosition chama a função de API ODBC SQLSetPos. O parâmetro wLockType especifica o estado de bloqueio da linha após a execução de SQLSetPos. A tabela a seguir descreve os valores possíveis de wLockType.

wLockType	Descrição
SQL_LOCK_NO_CHANGE (o valor padrão)	O driver ou a fonte de dados garante que a linha esteja no mesmo estado bloqueado ou desbloqueado como era antes de SetRowsetCursorPosition ser chamado.
SQL_LOCK_EXCLUSIVE	O driver ou a fonte de dados bloqueia a linha exclusivamente. Nem todas as fontes de dados suportam esse tipo de bloqueio.
SQL_LOCK_UNLOCK	O driver ou a fonte de dados desbloqueia a linha. Nem todas as fontes de dados suportam esse tipo de bloqueio.

Para obter mais informações sobre SQLSetPos, consulte o SDK do Windows. Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

CRecordset::SetRowsetSize

Especifica o número de registros que você deseja recuperar durante uma busca.

virtual void SetRowsetSize(DWORD dwNewRowsetSize);

Parâmetros

dwNewRowsetSize
O número de linhas a serem recuperadas durante uma determinada busca.

Comentários

Essa função de membro virtual especifica quantas linhas você deseja recuperar durante uma única busca ao usar a busca de linhas em massa. Para implementar a busca de linhas em massa, você deve definir a opção CRecordset::useMultiRowFetch no parâmetro dwOptions da função de membro Open.

Chame SetRowsetSize antes de chamar Open para definir inicialmente o tamanho do conjunto de linhas para o conjunto de registros. O tamanho padrão do conjunto de linhas ao implementar a busca de linhas em massa é 25.

Para obter a configuração atual para o tamanho do conjunto de linhas, chame GetRowsetSize.

Para obter mais informações sobre busca de linhas em massa, confira Conjunto de registros: buscando registros em massa (ODBC).

CRecordset::Update

Conclui uma operação AddNew ou Edit salvando os dados novos ou editados na fonte de dados.

virtual BOOL Update();

Valor retornado

Diferente de zero se um registro tiver sido atualizado com êxito; caso contrário, 0 se nenhuma coluna tiver sido alterada. Se nenhum registro tiver sido atualizado ou se mais de um registro tiver sido atualizado, uma exceção será gerada. Uma exceção também é gerada para qualquer outra falha na fonte de dados.

Comentários

Chame essa função de membro após uma chamada para a função de membro AddNew ou Edit. Essa chamada é necessária para concluir a operação AddNew ou Edit.

Tanto AddNew quanto Edit preparam um buffer de edição no qual os dados adicionados ou editados são colocados para salvar na fonte de dados. Update salva os dados. Somente os campos marcados ou detectados como alterados são atualizados.

Se a fonte de dados suportar transações, você fazer Update chamar (e sua chamada AddNew ou Edit correspondente) parte de uma transação. Para obter mais informações sobre transações, confira Transação (ODBC).

Para obter detalhes sobre como lidar com falhas Update, consulte Conjunto de registros: Como conjuntos de registros atualizam registros (ODBC).

Exemplo

confira Transação: realizando uma transação em um conjunto de registros (ODBC).

Confira também

CObject classe
Gráfico de hierarquia
CDatabase classe
CRecordView classe