Classe CRowset

Encapsula um objeto de conjunto de linhas OLE DB e várias interfaces relacionadas e fornece métodos de manipulação para dados de conjunto de linhas.

Sintaxe

template <class TAccessor = CAccessorBase>
class CRowset

Parâmetros

Cestor
Uma classe de acessador. A predefinição é CAccessorBase.

Requerimentos

Cabeçalho: atldbcli.h

Membros

Metodologia

Observações

No OLE DB, um conjunto de linhas é o objeto através do qual um programa define e recupera dados.

Esta classe não se destina a ser instanciada, mas sim passada como um parâmetro de modelo para CTable ou CCommand (CRowset é o padrão).

CRowset::AddRefRows

Chama IRowset::AddRefRows para incrementar (em um) a contagem de referência associada ao identificador de linha atual.

Sintaxe

HRESULT AddRefRows() throw();

Valor de retorno

Um HRESULT padrão.

Observações

Esse método incrementa a contagem de referência para o identificador de linha atual. Chame ReleaseRows para diminuir a contagem. As linhas retornadas pelos métodos move têm uma contagem de referência de um.

CRowset::Fechar

Libera linhas e a interface IRowset atual.

Sintaxe

void Close() throw();

Observações

Esse método libera todas as linhas atualmente no conjunto de linhas.

CRowset::Comparar

Compara dois marcadores usando IRowsetLocate::Compare.

Sintaxe

HRESULT Compare(const CBookmarkBase& bookmark1,
   const CBookmarkBase& bookmark2,
   DBCOMPARE* pComparison) const throw();

Parâmetros

Marcador1
[em] O primeiro marcador para comparar.

Marcador2
[em] O segundo marcador para comparar.

pComparação
[saídas] Um ponteiro para o resultado da comparação.

Valor de retorno

Um HRESULT padrão.

Observações

Este método requer a interface IRowsetLocateopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetLocate como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

Para obter informações sobre como usar marcadores em consumidores, consulte Usando marcadores.

CRowset::CRowset

Cria um novo CRowset objeto e (opcionalmente) associa-o a uma interface IRowset fornecida como parâmetro.

Sintaxe

CRowset();

CRowset(IRowset* pRowset);

Parâmetros

pConjunto de linhas
[em] Um ponteiro para uma IRowset interface a ser associada a essa classe.

CRowset::D elete

Chama IRowsetChange::D eleteRows para excluir a linha atual do conjunto de linhas.

Sintaxe

HRESULT Delete() const throw();

Valor de retorno

Um HRESULT padrão.

CRowset::FindNextRow

Localiza a próxima linha correspondente após o marcador especificado.

Sintaxe

HRESULT FindNextRow(DBCOMPAREOP op,
   BYTE* pData,
   DBTYPE wType,
   DBLENGTH nLength,
   BYTE bPrecision,
   BYTE bScale,
   BOOL bSkipCurrent = TRUE,
   CBookmarkBase* pBookmark = NULL) throw();

Parâmetros

PO
[em] A operação a ser usada na comparação de valores de linha. Para valores, consulte IRowsetFind::FindNextRow.

pDados
[em] Um ponteiro para o valor a ser correspondido.

wTipo
[em] Indica o tipo de dados da parte do valor do buffer. Para obter informações sobre indicadores de tipo, consulte Tipos de dados na referência do programador OLE DB no SDK do Windows.

nComprimento
[em] O comprimento, em bytes, da estrutura de dados do consumidor alocada para o valor de dados. Para obter detalhes, consulte a descrição de cbMaxLen em DBBINDING Structures na referência do programador OLE DB.

bPrecisão
[em] A precisão máxima usada ao obter dados. Usado somente se wType for DBTYPE_NUMERIC. Para obter mais informações, consulte Conversões envolvendo DBTYPE_NUMERIC ou DBTYPE_DECIMAL na Referência do programador OLE DB.

bEscala
[em] A escala usada ao obter dados. Usado somente se wType for DBTYPE_NUMERIC ou DBTYPE_DECIMAL. Para obter mais informações, consulte Conversões envolvendo DBTYPE_NUMERIC ou DBTYPE_DECIMAL na Referência do programador OLE DB.

bSkipAtual
[em] O número de linhas do marcador no qual iniciar uma pesquisa.

pMarcador
[em] O marcador para a posição na qual iniciar uma pesquisa.

Valor de retorno

Um HRESULT padrão.

Observações

Este método requer a interface IRowsetFindopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetFind como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

Para obter informações sobre como usar marcadores em consumidores, consulte Usando marcadores.

CRowset::GetApproximatePosition

Devolve a posição aproximada de uma linha correspondente a um marcador.

Sintaxe

HRESULT GetApproximatePosition(const CBookmarkBase* pBookmark,
   DBCOUNTITEM* pPosition,
   DBCOUNTITEM* pcRows) throw();

Parâmetros

pMarcador
[em] Um ponteiro para um indicador que identifica a linha cuja posição deve ser encontrada. NULL se apenas a contagem de linhas for necessária.

pPosição
[saídas] Um ponteiro para o local onde GetApproximatePosition retorna a posição da linha. NULL se a posição não for necessária.

pcRows
[saídas] Um ponteiro para o local onde GetApproximatePosition retorna o número total de linhas. NULL se a contagem de linhas não for necessária.

Valor de retorno

Um HRESULT padrão.

Observações

Este método requer a interface IRowsetScrollopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetScroll como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

Para obter informações sobre como usar marcadores em consumidores, consulte Usando marcadores.

CRowset::GetData

Recupera dados da cópia da linha do conjunto de linhas.

Sintaxe

HRESULT GetData() throw();

HRESULT GetData(int nAccessor) throw();

Parâmetros

nAcessor
[em] O número de índice (deslocamento zero) do acessador a ser usado para acessar os dados.

Valor de retorno

Um HRESULT padrão.

Observações

Se você especificar um acessador que não seja um acessador automático no BEGIN_ACCESSOR, use esse método para obter explicitamente os dados passando o número do acessador.

CRowset::GetDataHere

Recupera dados da linha atual e os coloca no buffer especificado.

Sintaxe

HRESULT GetDataHere(int nAccessor,
   void* pBuffer) throw();

Parâmetros

nAcessor
[em] O número de índice do acessador a ser usado para acessar os dados.

pBuffer
[saídas] Um buffer no qual colocar os dados para o registro atual.

Valor de retorno

Um HRESULT padrão.

Observações

Para obter um exemplo de como usar essa função, consulte o Exemplo de leitura múltipla.

CRowset::GetOriginalData

Chamadas IRowsetUpdate::GetOriginalData para recuperar os dados mais recentemente obtidos ou transmitidos para a fonte de dados.

Sintaxe

HRESULT GetOriginalData() throw();

Valor de retorno

Um HRESULT padrão.

Observações

Esse método recupera os dados mais recentemente obtidos ou transmitidos para a fonte de dados; ele não recupera valores com base em alterações pendentes.

Este método requer a interface IRowsetUpdateopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetUpdate como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

CRowset::GetRowStatus

Retorna o status de todas as linhas.

Sintaxe

HRESULT GetRowStatus(DBPENDINGSTATUS* pStatus) const throw();

Parâmetros

pStatus
[saídas] Um ponteiro para um local onde GetRowStatus retorna o valor de status. Consulte DBPENDINGSTATUS na Referência do programador OLE DB.

Valor de retorno

Um HRESULT padrão.

Observações

Este método requer a interface IRowsetUpdateopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetUpdate como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

CRowset::Inserir

Cria e inicializa uma nova linha usando dados do acessador.

Sintaxe

HRESULT Insert(int nAccessor = 0,
   bool bGetHRow = false) throw();

Parâmetros

nAcessor
[em] O número do acessador a ser usado para inserir os dados.

bGetHRow
[em] Indica se o identificador da linha inserida é recuperado.

Valor de retorno

Um HRESULT padrão.

Observações

Este método requer a interface IRowsetChangeopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetChange como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

Inserir pode falhar se uma ou mais colunas não forem graváveis. Modifique o mapa do cursor para corrigir isso.

Exemplo

O exemplo a seguir mostra como acessar uma fonte de dados por meio de um conjunto de linhas e, em seguida, inserir uma cadeia de caracteres usando uma tabela nesse conjunto de linhas.

Primeiro, crie uma classe de tabela inserindo um novo objeto ATL em seu projeto. Por exemplo, clique com o botão direito do mouse no projeto no painel Espaço de trabalho e selecione Novo objeto ATL. Na categoria Acesso a Dados , selecione Consumidor. Crie um objeto de consumidor do tipo Table. (Selecionar Tabela cria um conjunto de linhas diretamente da tabela; selecionar Comando cria um conjunto de linhas por meio de um comando SQL.) Selecione uma fonte de dados, especificando uma tabela através da qual acessar essa fonte de dados. Se você chamar seu objeto de consumidor CCustomerTable, implementará seu código de inserção da seguinte maneira:

// Access the rowset using the wizard-generated class, CCustomerTable
CCustomerTable rs;           // Your CTable-derived class

// Insert a customer
// Note that for fixed-length fields such as billing ID it isn't necessary
// to set the length
rs.m_BillingID = 5002;
rs.m_dwBillingIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_ContactFirstName, sizeof(rs.m_ContactFirstName) / sizeof(TCHAR), 
   _T("Malcolm"));
rs.m_dwContactFirstNameLength = 7;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_L_Name, sizeof(rs.m_L_Name) / sizeof(TCHAR), _T("Reynolds"));
rs.m_dwL_NameLength = 8;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

rs.m_CustomerID = 2005;
rs.m_dwCustomerIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_PostalCode, sizeof(rs.m_PostalCode) / sizeof(TCHAR), 
   _T("34213-4444"));
rs.m_dwPostalCodeLength = 10;
rs.m_dwPostalCodeStatus = DBSTATUS_S_OK;

HRESULT hr = rs.Insert();
if (FAILED(hr))
{
   ATLTRACE(_T("Insert failed: 0x%X\n"), hr);
}

CRowset::IsSameRow

Compara a linha especificada com a linha atual.

Sintaxe

HRESULT IsSameRow(HROW hRow) const throw();

Parâmetros

hRow
[em] Um identificador para a linha para comparar com a linha atual.

Valor de retorno

Um HRESULT padrão. S_OK indica que as linhas são as mesmas. Para outros valores, consulte IRowsetIndentity::IsSameRow na referência do programador OLE DB no SDK do Windows.

CRowset::MoveFirst

Move o cursor para a posição inicial e recupera a linha inicial.

Sintaxe

HRESULT MoveFirst() throw();

Valor de retorno

Um HRESULT padrão.

Observações

Chama IRowset::RestartPosition para reposicionar o local de próxima busca para a posição inicial (a posição que era o local de próxima busca quando o conjunto de linhas foi criado) e recupera a linha inicial.

CRowset::MoveLast

Move o cursor para a última linha.

Sintaxe

HRESULT MoveLast() throw();

Valor de retorno

Um HRESULT padrão.

Observações

Chama IRowset::RestartPosition para reposicionar o local de próxima busca para a última posição e recupera a última linha.

Esse método requer que você defina DBPROP_CANSCROLLBACKWARDS como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas. (Para um melhor desempenho, você também pode definir DBPROP_QUICKRESTART como VARIANT_TRUE.)

CRowset::MoveNext

Move o cursor para o próximo registro.

Sintaxe

HRESULT MoveNext() throw();

HRESULT MoveNext(LONG lSkip,
   bool bForward= true) throw();

Parâmetros

lSaltar
[em] O número de linhas a serem ignoradas antes de buscar.

bAvançar
[em] Passe true para avançar para o próximo disco, false para andar para trás.

Valor de retorno

Um HRESULT padrão. Quando o final do conjunto de linhas for atingido, retornará DB_S_ENDOFROWSET.

Observações

Busca a próxima linha sequencial do CRowset objeto, lembrando a posição anterior. Opcionalmente, você pode optar por pular linhas lSkip à frente ou retroceder.

Esse método requer que você defina as seguintes propriedades antes de chamar Open a tabela ou o comando que contém o conjunto de linhas:

• DBPROP_CANSCROLLBACKWARDS deve ser VARIANT_TRUE se lSkip< 0

• DBPROP_CANFETCHBACKWARDS deve ser VARIANT_TRUE se bForward = false

Caso contrário (se lSkip>= 0 e bForward = true), não será necessário definir nenhuma propriedade adicional.

CRowset::MovePrev

Move o cursor para o registro anterior.

Sintaxe

HRESULT MovePrev() throw();

Valor de retorno

Um HRESULT padrão.

Observações

Esse método requer que você defina um DBPROP_CANFETCHBACKWARDS ou DBPROP_CANSCROLLBACKWARDS para VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

CRowset::MoveToBookmark

Busca a linha marcada por um indicador ou a linha em um deslocamento especificado (lSkip) desse indicador.

Sintaxe

HRESULT MoveToBookmark(const CBookmarkBase& bookmark,
   LONG lSkip = 0) throw();

Parâmetros

marcador
[em] Um marcador que marca o local a partir do qual pretende obter dados.

lSaltar
[em] A contagem numérica de linhas do marcador para a linha de destino. Se lSkip for zero, a primeira linha buscada será a linha marcada. Se lSkip for 1, a primeira linha buscada será a linha após a linha marcada. Se lSkip for -1, a primeira linha buscada será a linha antes da linha marcada.

Valor de retorno

Um HRESULT padrão.

Observações

Este método requer a interface IRowsetLocateopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetLocate como VARIANT_TRUE e definir DBPROP_CANFETCHBACKWARDS como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

Para obter informações sobre como usar marcadores em consumidores, consulte Usando marcadores.

CRowset::MoveToRatio

Busca linhas a partir de uma posição fracionária no conjunto de linhas.

Sintaxe

HRESULT MoveToRatio(DBCOUNTITEM nNumerator,
   DBCOUNTITEM nDenominator,bool bForward = true) throw();

Parâmetros

nNumerador
[em] O numerador usado para determinar a posição fracionária a partir da qual buscar dados.

nDenominador
[em] O denominador usado para determinar a posição fracionária a partir da qual buscar dados.

bAvançar
[em] Indica se se deve avançar ou retroceder. O padrão é forward.

Valor de retorno

Um HRESULT padrão.

Observações

MoveToRatio Obtém linhas de acordo com aproximadamente a seguinte fórmula:

(nNumerator * RowsetSize ) / nDenominator

onde RowsetSize é o tamanho do conjunto de linhas, medido em linhas. A precisão desta fórmula depende do fornecedor específico. Para obter detalhes, consulte IRowsetScroll::GetRowsAtRatio.

Este método requer a interface IRowsetScrollopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetScroll como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

CRowset::ReleaseRows

Chama IRowset::ReleaseRows para liberar o identificador de linha atual.

Sintaxe

HRESULT ReleaseRows() throw();

Valor de retorno

Um HRESULT padrão.

CRowset::SetData

Define valores de dados em uma ou mais colunas de uma linha.

Sintaxe

HRESULT SetData() const throw();

HRESULT SetData(int nAccessor) const throw();

Parâmetros

nAcessor
[em] O número do acessador a ser usado para acessar os dados.

Valor de retorno

Um HRESULT padrão.

Observações

Para o SetData formulário que não aceita argumentos, todos os acessadores são usados para atualização. Normalmente, você chama SetData para definir valores de dados em colunas em uma linha e, em seguida, chama Update para transmitir essas alterações.

Este método requer a interface IRowsetChangeopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetChange como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

A operação de configuração pode falhar se uma ou mais colunas não forem graváveis. Modifique o mapa do cursor para corrigir isso.

CRowset::Desfazer

Desfaz todas as alterações feitas em uma linha desde a última busca ou atualização.

Sintaxe

HRESULT Undo(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

Parâmetros

pcRows
[saídas] Um ponteiro para o local onde retorna o número de linhas que Undo tentou desfazer, se necessário.

phRow [en]
[saídas] Um ponteiro para o local onde Undo retorna uma matriz de identificadores para todas as linhas que tentou desfazer, se necessário.

pStatus
[saídas] Um ponteiro para o local onde Undo retorna o valor de status da linha. Nenhum status será retornado se pStatus for null.

Valor de retorno

Um HRESULT padrão.

Observações

Este método requer a interface IRowsetUpdateopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetUpdate como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

CRowset::Atualização

Transmite quaisquer alterações pendentes feitas na linha atual desde a última busca ou Update chamada nela.

Sintaxe

HRESULT Update(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

Parâmetros

pcRows
[saídas] Um ponteiro para o local onde Update retorna o número de linhas que tentou atualizar, se necessário.

phRow [en]
[saídas] Um ponteiro para o local onde Update retorna o identificador da linha que tentou atualizar. Nenhum identificador será retornado se phRow for null.

pStatus
[saídas] Um ponteiro para o local onde Update retorna o valor de status da linha. Nenhum status será retornado se pStatus for null.

Valor de retorno

Um HRESULT padrão.

Observações

Transmite quaisquer alterações pendentes feitas na linha atual desde que essa linha foi buscada ou atualizada pela última vez (usando Update ou UpdateAll). Normalmente, você chama SetData para definir valores de dados em colunas em uma linha e, em seguida, chama Update para transmitir essas alterações.

Este método requer a interface IRowsetUpdateopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetUpdate como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

CRowset::UpdateAll

Transmite quaisquer alterações pendentes feitas em todas as linhas desde a última busca ou Update chamada.

Sintaxe

HRESULT UpdateAll(DBCOUNTITEM* pcRows = NULL,
   HROW** pphRow = NULL,
   DBROWSTATUS** ppStatus = NULL) throw();

Parâmetros

pcRows
[saídas] Um ponteiro para o local onde UpdateAll retorna o número de linhas que tentou atualizar, se necessário.

pphRow
[saídas] Um ponteiro para a memória no qual UpdateAll retorna o identificador da linha que tentou atualizar. Nenhum identificador será retornado se pphRow for null.

ppStatus
[saídas] Um ponteiro para o local onde Update retorna o valor de status da linha. Nenhum status será retornado se ppStatus for null.

Observações

Transmite todas as alterações pendentes feitas em todas as linhas desde a última vez que essas linhas foram buscadas ou atualizadas usando Update ou UpdateAll. UpdateAll atualizará todas as linhas que foram modificadas, independentemente de você ainda ter o identificador para elas (consulte pphRow) ou não.

Por exemplo, se você costumava Insert inserir cinco linhas em um conjunto de linhas, poderia ligar Update cinco vezes ou ligar UpdateAll uma vez para atualizá-las todas.

Este método requer a interface IRowsetUpdateopcional, que pode não ser suportada em todos os provedores, se este for o caso, o método retorna E_NOINTERFACE. Você também deve definir DBPROP_IRowsetUpdate como VARIANT_TRUE antes de chamar Open a tabela ou o comando que contém o conjunto de linhas.

Valor de retorno

Um HRESULT padrão.

Ver também

Exemplo DBViewer
Exemplo de leitura múltipla
Exemplo de atributos MultiRead
Modelos de consumidor OLE DB
Referência de modelos de consumidor OLE DB