Recordset: Buscar registros em massa (ODBC)

Artigo
02/25/2013

Este tópico se aplica a classes MFC ODBC.

Classe CRecordset fornece suporte para buscar de linha em massa, o que significa que vários registros podem ser recuperados de uma vez durante uma única busca, em vez de recuperar um registro por vez da fonte de dados.Você pode implementar em massa linha buscar em um derivado CRecordset classe.O processo de transferência de dados da fonte de dados para o objeto recordset é chamado em massa registro campo exchange (RFX em massa).Observe que se você não estiver usando em massa linha buscar em um CRecordset-classe derivada, os dados é transferido através da troca de campo de registro (RFX).Para obter mais informações, consulte Registro campo Exchange (RFX).

Este tópico explica:

Como CRecordset oferece suporte a busca de linha em massa.
Algumas considerações especiais quando usando em massa linha buscando.
Como implementar em massa registro campo exchange.

Como o suporte CRecordset em massa linha buscando

Antes de abrir seu objeto recordset, você pode definir um tamanho de conjunto de linhas com o SetRowsetSize função de membro.O tamanho do conjunto de linhas Especifica quantos registros devem ser recuperados durante uma única busca.Quando buscar de linha em massa é implementado, o tamanho do conjunto de linhas padrão é 25.Se não for implementado em massa linha buscando, o tamanho do conjunto de linhas permanece fixo em 1.

Depois de ter inicializado o tamanho do conjunto de linhas, chamar o Abrir função de membro.Aqui você deve especificar o CRecordset::useMultiRowFetch opção do dwOptions parâmetro para implementar em massa linha buscando.Além disso, você pode definir a CRecordset::userAllocMultiRowBuffers opção.O mecanismo de troca de campo de registro em massa usa matrizes para armazenar várias linhas de dados recuperados durante uma busca.Esses buffers de armazenamento podem ser alocados automaticamente pela estrutura ou alocá-las manualmente.Especificando o CRecordset::userAllocMultiRowBuffers opção significa que você fará a alocação.

A tabela a seguir lista as funções de membro fornecidas por CRecordset para suporte a busca de linha em massa.

Função de membro	Descrição
CheckRowsetError	Função virtual que trata os erros que ocorrem durante a busca.
DoBulkFieldExchange	Implementa em massa registro campo exchange.Chamado automaticamente para transferências de várias linhas de dados da fonte de dados para o objeto recordset.
GetRowsetSize	Recupera a configuração atual para o tamanho do conjunto de linhas.
GetRowsFetched	Informa quantas linhas foram realmente recuperadas após uma busca determinada.Na maioria dos casos, esse é o tamanho do conjunto de linhas, a menos que um conjunto de linhas incompleto foi encontrado.
GetRowStatus	Retorna um status de busca para uma linha específica em um conjunto de linhas.
RefreshRowset	Atualiza os dados e status de uma linha específica em um conjunto de linhas.
SetRowsetCursorPosition	Move o cursor para uma linha específica em um conjunto de linhas.
SetRowsetSize	Função virtual que altera a configuração de tamanho de conjunto de linhas para o valor especificado.

Considerações especiais

Embora a busca de linha em massa é um ganho de desempenho, determinados recursos operam de forma diferente.Antes de decidir implementar em massa linha buscando, considere o seguinte:

A estrutura automaticamente chama o DoBulkFieldExchange função de membro para transferir dados da fonte de dados para o objeto recordset.No entanto, dados não são transferidos do conjunto de registros para a origem de dados.Chamar o AddNew, Editar, Excluir, ou atualização resultados de funções de membro em uma declaração com falha.Embora CRecordset atualmente não fornece um mecanismo para atualizar linhas em massa de dados, você pode escrever suas próprias funções usando a função de API ODBC SQLSetPos.Para obter mais informações sobre SQLSetPos, consulte o referência do programador de ODBC SDK na documentação do MSDN.
As funções de membro IsDeleted, IsFieldDirty, IsFieldNull, IsFieldNullable, SetFieldDirty, e SetFieldNull não pode ser usado em conjuntos de registros que implementam em massa linha buscando.No entanto, você pode chamar GetRowStatus do IsDeleted, e GetODBCFieldInfo do IsFieldNullable.
O Mover operações reposiciona o conjunto de registros por conjunto de linhas.Por exemplo, suponha que você abrir um conjunto de registros possui 100 registros com um tamanho inicial do conjunto de linhas de 10.Abrir busca linhas 1 a 10, com o registro atual posicionado na linha 1.Uma chamada para MoveNext busca o próximo conjunto de linhas, a próxima linha.Este conjunto de linhas consiste em linhas 11 a 20, com o registro atual posicionadas na linha 11.Observe que MoveNext e Mover (1) não são equivalentes quando buscar de linha em massa é implementado.Mover (1) busca o conjunto de linhas que começa 1 linha do registro atual.Neste exemplo, chamando Mover (1) depois de chamar o Abrir busca o conjunto de linhas que consiste em linhas 2 a 11, com o registro atual posicionado na linha 2.Para obter mais informações, consulte o Mover função de membro.
Diferentemente de troca de campo de registro, os assistentes não oferecem suporte a exchange de campo de registro em massa.Isso significa que você deve manualmente declare os membros de dados de campo e substituir manualmente DoBulkFieldExchange gravando chamadas para as funções de RFX em massa.Para obter mais informações, consulte Registro campo Exchange funções na Referência de biblioteca de classe.

Como implementar em massa registro campo Exchange

Massa registro campo exchange transfere um conjunto de linhas de dados da fonte de dados para o objeto recordset.As funções de RFX em massa usarem matrizes para armazenar dados, bem como matrizes para armazenar o comprimento de cada item de dados no conjunto de linhas.Definição de classe, você deve definir os membros de dados do campo como ponteiros para acessar os conjuntos de dados.Além disso, você deve definir um conjunto de ponteiros para acessar as matrizes de comprimentos.Os membros de dados de parâmetro não devem ser declarados como ponteiros; declarar membros de dados de parâmetro ao usar o exchange de campo de registro em massa é igual a declará-los ao usar a troca de campo de registro.O código a seguir mostra um exemplo simples:

class MultiRowSet : public CRecordset
{
public:
   // Field/Param Data
      // field data members
      long* m_rgID;
      LPSTR m_rgName;

      // pointers for the lengths
      // of the field data
      long* m_rgIDLengths;
      long* m_rgNameLengths;

      // input parameter data member
      CString m_strNameParam;

   .
   .
   .
}

Você pode alocar esses buffers de armazenamento manualmente ou ter o framework faça a alocação.Para alocar os buffers, você deve especificar o CRecordset::userAllocMultiRowBuffers opção do dwOptions parâmetro na Abrir função de membro.Certifique-se de definir os tamanhos dos arrays de pelo menos igual ao tamanho do conjunto de linhas.Se você deseja ter o framework faça a alocação, você deve inicializar ponteiros para nulo. Isso geralmente é feito no construtor do objeto recordset:

MultiRowSet::MultiRowSet( CDatabase* pDB )
   : CRecordset( pDB )
{
   m_rgID = NULL;
   m_rgName = NULL;
   m_rgIDLengths = NULL;
   m_rgNameLengths = NULL;
   m_strNameParam = "";

   m_nFields = 2;
   m_nParams = 1;

   .
   .
   .
}

Finalmente, você deve substituir o DoBulkFieldExchange função de membro.Para os membros de dados de campo, chamar as funções RFX em massa; para quaisquer membros de dados de parâmetro, chame as funções RFX.Se você abriu o recordset passando uma instrução de SQL ou procedimento armazenado para Abrir, a ordem na qual você fazer chamadas RFX em massa deve corresponder à ordem de colunas no conjunto de registros; da mesma forma, a ordem das chamadas RFX parâmetros deve corresponder a ordem dos parâmetros na instrução SQL ou procedimento armazenado.

void MultiRowSet::DoBulkFieldExchange( CFieldExchange* pFX )
{
   // call the Bulk RFX functions
   // for field data members
   pFX->SetFieldType( CFieldExchange::outputColumn );
   RFX_Long_Bulk( pFX, _T( "[colRecID]" ),
                  &m_rgID, &m_rgIDLengths );
   RFX_Text_Bulk( pFX, _T( "[colName]" ),
                  &m_rgName, &m_rgNameLengths, 30 );


   // call the RFX functions for
   // for parameter data members
   pFX->SetFieldType( CFieldExchange::inputParam );
   RFX_Text( pFX, "NameParam", m_strNameParam );
}

Observação
Você deve chamar o Fechar função de membro antes derivada CRecordset classe sai do escopo.Isso garante que qualquer memória alocada pela estrutura são liberados.É boa prática sempre explicitamente chamada de programação Fechar, independentemente de se ter implementado em massa linha buscando.