Classe CDynamicAccessor

Artigo
08/03/2024

Permite que você acesse uma fonte de dados quando não tiver conhecimento do esquema de banco de dados (a estrutura subjacente do banco de dados).

Sintaxe

class CDynamicAccessor : public CAccessorBase

Requisitos

Cabeçalho: atldbcli.h

Membros

Métodos

Nome	Descrição
AddBindEntry	Adiciona uma entrada de associação às colunas de saída ao substituir o acessador padrão.
CDynamicAccessor	Cria uma instância e inicializa o objeto `CDynamicAccessor`.
Fechar	Desvincula todas as colunas, libera a memória alocada e libera o ponteiro de interface IAccessor na classe.
GetBlobHandling	Recupera o valor do processamento do BLOB para a linha atual.
GetBlobSizeLimit	Recupera o tamanho máximo do BLOB em bytes.
GetBookmark	Recupera o indicador da linha atual.
GetColumnCount	Recupera o número de colunas no conjunto de linhas.
GetColumnFlags	Recupera as características da coluna.
GetColumnInfo	Recupera os metadados da coluna.
GetColumnName	Recupera o nome da coluna especificada.
GetColumnType	Recupera o tipo de dados da coluna especificada.
GetLength	Recupera o comprimento máximo possível de uma coluna em bytes.
GetOrdinal	Recupera o índice de coluna dado um nome de coluna.
GetStatus	Recupera o status da coluna especificada.
GetValue	Recupera os dados do buffer.
SetBlobHandling	Define o valor do processamento do BLOB para a linha atual.
SetBlobSizeLimit	Define o tamanho máximo do BLOB em bytes.
SetLength	Define o comprimento da coluna em bytes.
SetStatus	Define o status da coluna especificada.
SetValue	Armazena os dados no buffer.

Comentários

Use métodos CDynamicAccessor para obter informações de coluna, como nomes de coluna, contagem de colunas, tipo de dados e assim por diante. Em seguida, use essas informações de coluna para criar um acessador dinamicamente em tempo de execução.

As informações da coluna são armazenadas em um buffer que é criado e gerenciado por essa classe. Obtenha dados do buffer usando GetValue.

Para obter uma discussão e exemplos de como usar as classes de acessador dinâmico, confira Uso de acessadores dinâmicos.

CDynamicAccessor::AddBindEntry

Adiciona uma entrada de associação às colunas de saída.

Sintaxe

HRESULT AddBindEntry(const DBCOLUMNINFO& info) throw();

Parâmetros

info
[in] Uma estrutura DBCOLUMNINFO contendo informações da coluna. Confira "Estruturas DBCOLUMNINFO" em IColumnsInfo::GetColumnInfo na Referência do Programador do OLE DB.

Valor de retorno

Um dos valores HRESULT padrão.

Comentários

Use esse método ao substituir o acessador padrão criado com CDynamicAccessor (confira Como buscar dados?).

CDynamicAccessor::CDynamicAccessor

Cria uma instância e inicializa o objeto CDynamicAccessor.

Sintaxe

CDynamicAccessor(DBBLOBHANDLINGENUM eBlobHandling = DBBLOBHANDLING_DEFAULT,
   DBLENGTH nBlobSize = 8000);

Parâmetros

eBlobHandling
Especifica como os dados do BLOB (objeto binário grande) devem ser processados. O valor padrão é DBBLOBHANDLING_DEFAULT. Confira SetBlobHandling para obter uma descrição dos valores de DBBLOBHANDLINGENUM.

nBlobSize
O tamanho máximo do BLOB em bytes; os dados da coluna sobre esse valor são tratados como um BLOB. O valor padrão é 8.000. Confira SetBlobSizeLimit para obter detalhes.

Comentários

Se você usar o construtor para inicializar o objeto CDynamicAccessor, poderá especificar como ele associará BLOBs. Os BLOBs podem conter dados binários, como gráficos, som ou código compilado. O comportamento padrão é tratar colunas com mais de 8.000 bytes como BLOBs e tentar associá-las a um objeto ISequentialStream. No entanto, você pode especificar um valor diferente para ser o tamanho do BLOB.

Você também pode especificar como CDynamicAccessor lida com dados de coluna que se qualificam como dados BLOB: ele pode lidar com dados BLOB da maneira padrão; ele pode ignorar (não associar) dados BLOB; ou pode associar dados BLOB na memória alocada pelo provedor.

CDynamicAccessor::Close

Desvincula todas as colunas, libera a memória alocada e libera o ponteiro de interface IAccessor na classe.

Sintaxe

void Close() throw();

CDynamicAccessor::GetBlobHandling

Recupera o valor do processamento do BLOB para a linha atual.

Sintaxe

const DBBLOBHANDLINGENUM GetBlobHandling() const;

Comentários

Retorna o valor do processamento do BLOB eBlobHandling conforme definido por SetBlobHandling.

CDynamicAccessor::GetBlobSizeLimit

Recupera o tamanho máximo do BLOB em bytes.

Sintaxe

const DBLENGTH GetBlobSizeLimit() const;

Comentários

Retorna o valor do processamento do BLOB nBlobSize conforme definido por SetBlobSizeLimit.

CDynamicAccessor::GetBookmark

Recupera o indicador da linha atual.

Sintaxe

HRESULT GetBookmark(CBookmark< >* pBookmark) const throw();

Parâmetros

pBookmark
[out] Um ponteiro para o objeto CBookmark.

Valor de retorno

Um dos valores HRESULT padrão.

Comentários

Você precisa definir DBPROP_IRowsetLocate como VARIANT_TRUE para recuperar um indicador.

CDynamicAccessor::GetColumnCount

Recupera o número de colunas.

Sintaxe

DBORDINAL GetColumnCount() const throw();

Valor retornado

O número de colunas recuperadas.

CDynamicAccessor::GetColumnFlags

Recupera as características da coluna.

Sintaxe

bool GetColumnFlags(DBORDINAL nColumn,
   DBCOLUMNFLAGS* pFlags) const throw();

Parâmetros

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

pFlags
[out] Um ponteiro para uma máscara de bits que descreve as características da coluna. Confira "Tipo enumerado DBCOLUMNFLAGS" em IColumnsInfo::GetColumnInfo na Referência do Programador do OLE DB.

Valor de retorno

Retorna true se as características da coluna forem recuperadas com êxito. Caso contrário, ele retornará false.

Comentários

O número da coluna começa pelo número um. A coluna zero é um caso especial; é o marcador, se disponível.

CDynamicAccessor::GetColumnInfo

Retorna os metadados de coluna necessários para a maioria dos consumidores.

Sintaxe

HRESULT GetColumnInfo(IRowset* pRowset,
   DBORDINAL* pColumns,
   DBCOLUMNINFO** ppColumnInfo,
   OLECHAR** ppStringsBuffer) throw();

Parâmetros

pRowset
[in] Um ponteiro para a interface IRowset .

pColumns
[out] Um ponteiro para a memória no qual retornar o número de colunas no conjunto de linhas; esse número inclui a coluna de indicador, se houver.

ppColumnInfo
[out] Um ponteiro para a memória, no qual retornar uma matriz de estruturas DBCOLUMNINFO. Confira "Estruturas DBCOLUMNINFO" em IColumnsInfo::GetColumnInfo na Referência do Programador do OLE DB.

ppStringsBuffer
[out] Um ponteiro para a memória no qual retornar um ponteiro para o armazenamento para todos os valores de cadeia de caracteres (nomes usados em columnid ou para pwszName) dentro de um único bloco de alocação.

Valor de retorno

Um dos valores HRESULT padrão.

Comentários

Confira IColumnsInfo::GetColumnInfo na Referência do Programador do OLE DB para obter informações sobre os tipos de dados DBORDINAL, DBCOLUMNINFO e OLECHAR.

CDynamicAccessor::GetColumnName

Recupera o nome da coluna especificada.

Sintaxe

LPOLESTR GetColumnName(DBORDINAL nColumn) const throw();

Parâmetros

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

Valor de retorno

O nome da coluna especificada.

CDynamicAccessor::GetColumnType

Recupera o tipo de dados da coluna especificada.

Sintaxe

bool GetColumnType(DBORDINAL nColumn,
   DBTYPE* pType) const throw();

Parâmetros

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

pType
[out] Um ponteiro para o tipo de dados da coluna especificada.

Valor de retorno

Retornará true se houver êxito ou false se houver falha.

CDynamicAccessor::GetLength

Recupera o comprimento da coluna especificada.

Sintaxe

bool GetLength(DBORDINAL nColumn,
   DBLENGTH* pLength) const throw();

bool GetLength(const CHAR* pColumnName,
   DBLENGTH* pLength) const throw();

bool GetLength(const WCHAR* pColumnName,
   DBLENGTH* pLength) const throw();

Parâmetros

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

pColumnName
[in] Um ponteiro para uma cadeia de caracteres que contém o nome da coluna.

pLength
[out] Um ponteiro para o inteiro que contém o comprimento da coluna em bytes.

Valor de retorno

Retorna true se a coluna especificada for encontrada. Caso contrário, essa função retornará false.

Comentários

A primeira substituição usa o número da coluna e a segunda e a terceira substituições usam o nome da coluna no formato ANSI ou Unicode, respectivamente.

CDynamicAccessor::GetOrdinal

Recupera o número da coluna dado um nome de coluna.

Sintaxe

bool GetOrdinal(const CHAR* pColumnName,
   DBORDINAL* pOrdinal) const throw();

bool GetOrdinal(const WCHAR* pColumnName,
   DBORDINAL* pOrdinal) const throw();

Parâmetros

pColumnName
[in] Um ponteiro para uma cadeia de caracteres que contém o nome da coluna.

pOrdinal
[out] Um ponteiro para o número da coluna.

Valor de retorno

Retorna true se uma coluna com o nome especificado for encontrada. Caso contrário, essa função retornará false.

CDynamicAccessor::GetStatus

Recupera o status da coluna especificada.

Sintaxe

bool GetStatus(DBORDINAL nColumn,
   DBSTATUS* pStatus) const throw();

bool GetStatus(const CHAR* pColumnName,
   DBSTATUS* pStatus) const throw();

bool GetStatus(const WCHAR* pColumnName,
   DBSTATUS* pStatus) const throw();

Parâmetros

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

pColumnName
[in] Um ponteiro para uma cadeia de caracteres que contém o nome da coluna.

pStatus
[out] Um ponteiro para a variável que contém o status da coluna. Confira DBSTATUS na Referência do Programador do OLE DB para obter mais informações.

Valor de retorno

Retorna true se a coluna especificada for encontrada. Caso contrário, essa função retornará false.

CDynamicAccessor::GetValue

Recupera os dados da coluna especificada.

Sintaxe

void* GetValue(DBORDINAL nColumn) const throw();

void* GetValue(const CHAR* pColumnName) const throw();

void* GetValue(const WCHAR* pColumnName) const throw();

template < class ctype >
bool GetValue(DBORDINAL nColumn, ctype* pData) const throw();

template < class ctype >
bool GetValue(const CHAR* pColumnName, ctype* pData) const throw();

template < class ctype >
bool GetValue(const WCHAR* pColumnName, ctype* pData) const throw();

Parâmetros

ctype
[in] Um parâmetro de modelo que processa qualquer tipo de dados, exceto tipos de cadeia de caracteres (CHAR*, WCHAR*), que requerem processamento especial. GetValue usa o tipo de dados apropriado com base no que você especifica aqui.

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

pColumnName
[in] O nome da coluna.

pData
[out] O ponteiro para o conteúdo da coluna especificada.

Valor de retorno

Se você quiser passar dados de cadeia de caracteres, use as versões sem modelo de GetValue. As versões sem modelo desse método retornam void*, que aponta para a parte do buffer que contém os dados de coluna especificados. Retorna NULL se a coluna não for encontrada.

Para todos os outros tipos de dados, é mais simples usar as versões com modelo de GetValue. As versões com modelo retornam true em caso de sucesso ou false em caso de falha.

Comentários

Use as versões sem modelo para retornar colunas que contêm cadeias de caracteres e as versões com modelo para colunas que contêm outros tipos de dados.

No modo de depuração, você receberá uma declaração se o tamanho do pData for diferente do tamanho da coluna para a qual ele aponta.

CDynamicAccessor::SetBlobHandling

Define o valor do processamento do BLOB para a linha atual.

Sintaxe

bool SetBlobHandling(DBBLOBHANDLINGENUM eBlobHandling);

Parâmetros

eBlobHandling
Especifica como os dados do BLOB devem ser processados. Ele pode usar os seguintes valores:

DBBLOBHANDLING_DEFAULT: manipule dados de coluna maiores que nBlobSize (conforme definido por SetBlobSizeLimit) como dados BLOB e recupere-os por meio de um objeto ISequentialStream ou IStream. Essa opção tentará associar todas as colunas que contêm dados maiores que nBlobSize ou listados como DBTYPE_IUNKNOWN como dados BLOB.
DBBLOBHANDLING_NOSTREAMS: trate dados de coluna maiores que nBlobSize (conforme definido por SetBlobSizeLimit) como dados BLOB e recupere-os por meio de referência na memória alocada pelo provedor e de propriedade do consumidor. Essa opção é útil para tabelas que têm mais de uma coluna BLOB e o provedor dá suporte a apenas um objeto ISequentialStream por acessador.
DBBLOBHANDLING_SKIP: ignorar (não associar) colunas qualificadas como contendo BLOBs (o acessador não associará nem recuperará o valor da coluna, mas ainda recuperará o status e o comprimento da coluna).

Comentários

Você deve chamar SetBlobHandling antes de chamar Open.

O método de construtor CDynamicAccessor define o valor de processamento de BLOB como DBBLOBHANDLING_DEFAULT.

CDynamicAccessor::SetBlobSizeLimit

Define o tamanho máximo do BLOB em bytes.

Sintaxe

void SetBlobSizeLimit(DBLENGTH nBlobSize);

Parâmetros

nBlobSize
Especifica o limite de tamanho do BLOB.

Comentários

Define o tamanho máximo do BLOB em bytes; dados de coluna maiores que esse valor são tratados como um BLOB. Alguns provedores determinam tamanhos extremamente grandes para colunas (como 2 GB). Em vez de tentar alocar memória para uma coluna desse tamanho, você normalmente tentará associar essas colunas como BLOBs. Dessa forma, você não precisa alocar toda a memória, mas ainda pode ler todos os dados sem medo de truncamento. No entanto, há alguns casos em que talvez você queira forçar CDynamicAccessor a associar colunas grandes em seus tipos de dados nativos. Para fazer isso, chame SetBlobSizeLimit antes de chamar Open.

O método de construtor CDynamicAccessor define o tamanho máximo do BLOB como um valor padrão de 8.000 bytes.

CDynamicAccessor::SetLength

Define o comprimento da coluna especificada.

Sintaxe

bool SetLength(DBORDINAL nColumn,
   DBLENGTH nLength)throw();

bool SetLength(const CHAR* pColumnName,
   DBLENGTH nLength) throw();

bool SetLength(const WCHAR* pColumnName,
   DBLENGTH nLength) throw();

Parâmetros

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

nLength
[in] O comprimento da coluna em bytes.

pColumnName
[in] Um ponteiro para uma cadeia de caracteres que contém o nome da coluna.

Valor de retorno

Retorna true se o comprimento da coluna especificado for definido com êxito. Caso contrário, essa função retornará false.

CDynamicAccessor::SetStatus

Define o status da coluna especificada.

Sintaxe

bool SetStatus(DBORDINAL nColumn,
   DBSTATUS status)throw();

bool SetStatus(const CHAR* pColumnName,
   DBSTATUS status) throw();

bool SetStatus(const WCHAR* pColumnName,
   DBSTATUS status) throw();

Parâmetros

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

status
[in] O status da coluna. Confira DBSTATUS na Referência do Programador do OLE DB para obter mais informações.

pColumnName
[in] Um ponteiro para uma cadeia de caracteres que contém o nome da coluna.

Valor de retorno

Retorna true se o status da coluna especificado for definido com sucesso. Caso contrário, essa função retornará false.

CDynamicAccessor::SetValue

Armazena dados em uma coluna especificada.

Sintaxe

template <class ctype>
bool SetValue(
   DBORDINAL nColumn,
   constctype& data) throw( );

template <class ctype>
bool SetValue(
   const CHAR * pColumnName,
   const ctype& data) throw( );

template <class ctype>
bool SetValue(
   const WCHAR *pColumnName,
   const ctype& data) throw( );

Parâmetros

pColumnName
[in] Um ponteiro para uma cadeia de caracteres que contém o nome da coluna.

data
[in] O ponteiro para a memória que contém os dados.

nColumn
[in] O número da coluna. Os números das colunas começam com 1. Um valor de 0 refere-se à coluna do indicador, se houver.

Valor de retorno

Se você quiser definir dados de cadeia de caracteres, use as versões sem modelo de GetValue. As versões sem modelo desse método retornam void*, que aponta para a parte do buffer que contém os dados de coluna especificados. Retorna NULL se a coluna não for encontrada.

Para todos os outros tipos de dados, é mais simples usar as versões com modelo de GetValue. As versões com modelo retornam true em caso de sucesso ou false em caso de falha.

Confira também

Modelos de consumidor OLE DB
Referência de modelos de consumidor do OLE DB
Classe CAccessor
Classe CDynamicParameterAccessor
Classe CManualAccessor

Compartilhar via

Classe CDynamicAccessor

Sintaxe

Requisitos

Membros

Métodos

Comentários

CDynamicAccessor::AddBindEntry

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDynamicAccessor::CDynamicAccessor

Sintaxe

Parâmetros

Comentários

CDynamicAccessor::Close

Sintaxe

CDynamicAccessor::GetBlobHandling

Sintaxe

Comentários

CDynamicAccessor::GetBlobSizeLimit

Sintaxe

Comentários

CDynamicAccessor::GetBookmark

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDynamicAccessor::GetColumnCount

Sintaxe

Valor retornado

CDynamicAccessor::GetColumnFlags

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDynamicAccessor::GetColumnInfo

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDynamicAccessor::GetColumnName

Sintaxe

Parâmetros

Valor de retorno

CDynamicAccessor::GetColumnType

Sintaxe

Parâmetros

Valor de retorno

CDynamicAccessor::GetLength

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDynamicAccessor::GetOrdinal

Sintaxe

Parâmetros

Valor de retorno

CDynamicAccessor::GetStatus

Sintaxe

Parâmetros

Valor de retorno

CDynamicAccessor::GetValue

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDynamicAccessor::SetBlobHandling

Sintaxe

Parâmetros

Comentários

CDynamicAccessor::SetBlobSizeLimit

Sintaxe

Parâmetros

Comentários

CDynamicAccessor::SetLength

Sintaxe

Parâmetros

Valor de retorno