O conjunto de registros: Buscar registros em massa (ODBC)

Artigo
08/01/2011

Este tópico se aplica às 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 a busca de linha em massa em um derivado CRecordset classe. O processo de transferência de dados da fonte de dados para o objeto recordset é denominado exchange de campo de registro em massa (Bulk RFX). Observe que, se você não estiver usando a busca de linha em massa em uma CRecordset-classe derivada, os dados é transferido por meio de troca de campo de registro (RFX). Para obter mais informações, consulte Exchange de campo do registro (RFX).

Este tópico explica:

Como o CRecordset oferece suporte a busca de linha em massa.
Algumas considerações especiais ao usar em massa linha buscando.
Como implementar a troca de campo de registro de massa.

Como o CRecordset suporta em massa buscar de linha

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 a busca de linha em massa é implementada, o tamanho do conjunto de linhas padrão é 25. Se não for implementada em massa buscar de linha, o tamanho do conjunto de linhas permanece fixo em 1.

Após você ter inicializado o tamanho do conjunto de linhas, chame o Abrir a função de membro. Aqui, você deve especificar o CRecordset::useMultiRowFetch a opção do dwOptions parâmetro para implementar a busca de linha em massa. 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 pelo framework ou alocá-las manualmente. Especificando a CRecordset::userAllocMultiRowBuffers opção significa que você faça a alocação.

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

Função de membro	Description
CheckRowsetError	Função virtual que trata os erros que ocorrem durante a busca.
DoBulkFieldExchange	Implementa em massa a troca de campo do registro. 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 determinada busca. Na maioria dos casos, isso é 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 dentro de um conjunto de linhas.
RefreshRowset	Atualiza os dados e o status de uma linha específica dentro de um conjunto de linhas.
SetRowsetCursorPosition	Move o cursor para uma linha específica dentro de um conjunto de linhas.
SetRowsetSize	Função virtual que altera a configuração para o tamanho do 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 a busca de linha em massa, considere o seguinte:

O framework chama automaticamente o DoBulkFieldExchange a 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 volta para a fonte 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 fornecem um mecanismo para a atualização em massa de linhas 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 a busca de linha em massa. No entanto, você pode chamar GetRowStatus no lugar de IsDeleted, e GetODBCFieldInfo no lugar de IsFieldNullable.
O Mover operações reposiciona o conjunto de registros por um conjunto de linhas. Por exemplo, suponha que você abrir um conjunto de registros tem 100 registros com um tamanho inicial do conjunto de linhas de 10. Abrir busca linhas de 1 a 10, com o registro atual posicionado na linha 1. Uma chamada para MoveNext busca linhas próxima, não 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 ao buscar a linha em massa é implementado. Mover a (1) busca o conjunto de linhas que começa 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 de 2 a 11, com o registro atual posicionado na linha 2. Para obter mais informações, consulte o Mover a função de membro.
Ao contrário de troca de campo de registro, os assistentes não oferecem suporte a troca de campo de registro de massa. Isso significa que você deve declarar manualmente os seus membros de dados de campo e substituir manualmente DoBulkFieldExchange escrevendo chamadas a funções de RFX de massa. Para obter mais informações, consulte Funções do Exchange de campo de registro na Referência da biblioteca de classe.

Como a troca de campo do registro de implementar em massa

Troca de campo de registro de massa transfere um conjunto de linhas de dados da fonte de dados para o objeto recordset. As funções de RFX de massa usarem matrizes para armazenar esses 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 comprimento. 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 do campo de registro em massa é igual a declará-los ao usar a troca de campo do 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 a estrutura para fazer a alocação. Para alocar os buffers, você deve especificar o CRecordset::userAllocMultiRowBuffers a opção do dwOptions parâmetro no Abrir a função de membro. Certifique-se de definir os tamanhos das matrizes no mínimo igual ao tamanho do conjunto de linhas. Se você quiser ter a estrutura para fazer a alocação, você deve inicializar os ponteiros para nulo. Normalmente, isso é feito no construtor do objeto de conjunto de registros:

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 de RFX de massa; para quaisquer membros de dados de parâmetro, chame as funções RFX. Se você abriu o conjunto de registros, passando de uma instrução de SQL ou o procedimento armazenado para Abrir, a ordem na qual você fazer as chamadas de RFX de massa deve corresponder à ordem de colunas no conjunto de registros; da mesma forma, a ordem das chamadas RFX de parâmetros deve corresponder à ordem de 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 a função de membro antes derivada CRecordset classe sai do escopo. Isso garante que toda a memória alocada pelo framework são liberados. É uma boa prática sempre explicitamente chamada de programação Fechar, independentemente de se você implementou a busca de linha em massa.