Macros para modelos de provedor de banco de dados OLE

Artigo
04/03/2023

As macros do Provedor de Modelos OLE DB oferecem funcionalidade nas seguintes categorias:

Macros de mapa de conjunto de propriedades

Nome	Descrição
BEGIN_PROPERTY_SET	Marca o início de um conjunto de propriedades.
BEGIN_PROPERTY_SET_EX	Marca o início de um conjunto de propriedades.
BEGIN_PROPSET_MAP	Marca o início de um conjunto de propriedades que pode ser oculto ou definido fora do escopo do provedor.
CHAIN_PROPERTY_SET	Encadeia grupos de propriedades.
END_PROPERTY_SET	Marca o final de um conjunto de propriedades.
END_PROPSET_MAP	Marca o final de um mapa de conjunto de propriedades.
PROPERTY_INFO_ENTRY	Define uma propriedade específica em um conjunto de propriedades como um valor padrão.
PROPERTY_INFO_ENTRY_EX	Define uma propriedade específica em um conjunto de propriedades como um valor fornecido por você. Também permite que você defina sinalizadores e opções.
PROPERTY_INFO_ENTRY_VALUE	Define uma propriedade específica em um conjunto de propriedades como um valor fornecido por você.

Macros de mapa de colunas

Nome	Descrição
BEGIN_PROVIDER_COLUMN_MAP	Marca o início das entradas do mapa de colunas do provedor.
END_PROVIDER_COLUMN_MAP	Marca o final das entradas do mapa de colunas do provedor.
PROVIDER_COLUMN_ENTRY	Representa uma coluna específica com suporte do provedor.
PROVIDER_COLUMN_ENTRY_FIXED	Representa uma coluna específica com suporte do provedor. Você pode especificar o tipo de dados de coluna.
PROVIDER_COLUMN_ENTRY_GN	Representa uma coluna específica com suporte do provedor. Você pode especificar o tamanho da coluna, o tipo de dados, a precisão, a escala e o GUID do conjunto de linhas de esquema.
PROVIDER_COLUMN_ENTRY_LENGTH	Representa uma coluna específica com suporte do provedor. Você pode especificar o tamanho da coluna.
PROVIDER_COLUMN_ENTRY_STR	Representa uma coluna específica com suporte do provedor. Ele pressupõe que o tipo de coluna seja uma cadeia de caracteres.
PROVIDER_COLUMN_ENTRY_TYPE_LENGTH	Representa uma coluna específica com suporte do provedor. Como PROVIDER_COLUMN_ENTRY_LENGTH, mas também permite que você especifique o tipo de dados da coluna, bem como o tamanho.
PROVIDER_COLUMN_ENTRY_WSTR	Representa uma coluna específica com suporte do provedor. Ele pressupõe que o tipo de coluna seja uma cadeia de caracteres Unicode.

Macros de conjunto de linhas de esquema

Nome	Descrição
BEGIN_SCHEMA_MAP	Marca o início de um mapa de esquema.
END_SCHEMA_MAP	Marca o fim de um mapa de esquema.
SCHEMA_ENTRY	Associa um GUID a uma classe.

Requisitos

Cabeçalho: atldb.h

BEGIN_PROPERTY_SET

Marca o início de um conjunto de propriedades em um mapa de conjunto de propriedades.

Sintaxe

BEGIN_PROPERTY_SET(guid)

Parâmetros

guid
[in] O nome do GUID.

Exemplo

Confira BEGIN_PROPSET_MAP.

BEGIN_PROPERTY_SET_EX

Marca o início de um conjunto de propriedades em um mapa de conjunto de propriedades.

Sintaxe

BEGIN_PROPERTY_SET_EX(guid, flags)

Parâmetros

guid
[in] O nome do GUID.

sinalizadores
[in] UPROPSET_HIDDEN para quaisquer conjuntos de propriedades que você não deseja expor ou UPROPSET_PASSTHROUGH para um provedor expor propriedades definidas fora do escopo do provedor.

Exemplo

Confira BEGIN_PROPSET_MAP.

BEGIN_PROPSET_MAP

Marca o início das entradas do mapa do conjunto de propriedades.

Sintaxe

BEGIN_PROPSET_MAP(Class)

Parâmetros

Classe
[in] A classe na qual esse conjunto de propriedades é especificado. Um conjunto de propriedades pode ser especificado nos seguintes objetos OLE DB:

Exemplo

Aqui está um mapa de conjunto de propriedades de exemplo:

BEGIN_PROPSET_MAP(CCustomSource)
    BEGIN_PROPERTY_SET(DBPROPSET_DATASOURCEINFO)
        PROPERTY_INFO_ENTRY(ACTIVESESSIONS)
        PROPERTY_INFO_ENTRY(DATASOURCEREADONLY)
        PROPERTY_INFO_ENTRY(BYREFACCESSORS)
        PROPERTY_INFO_ENTRY(OUTPUTPARAMETERAVAILABILITY)
        PROPERTY_INFO_ENTRY(PROVIDEROLEDBVER)
        PROPERTY_INFO_ENTRY(DSOTHREADMODEL)
        PROPERTY_INFO_ENTRY(SUPPORTEDTXNISOLEVELS)
        PROPERTY_INFO_ENTRY(USERNAME)
    END_PROPERTY_SET(DBPROPSET_DATASOURCEINFO)
    BEGIN_PROPERTY_SET(DBPROPSET_DBINIT)
        PROPERTY_INFO_ENTRY(AUTH_PASSWORD)
        PROPERTY_INFO_ENTRY(AUTH_PERSIST_SENSITIVE_AUTHINFO)
        PROPERTY_INFO_ENTRY(AUTH_USERID)
        PROPERTY_INFO_ENTRY(INIT_DATASOURCE)
        PROPERTY_INFO_ENTRY(INIT_HWND)
        PROPERTY_INFO_ENTRY(INIT_LCID)
        PROPERTY_INFO_ENTRY(INIT_LOCATION)
        PROPERTY_INFO_ENTRY(INIT_MODE)
        PROPERTY_INFO_ENTRY(INIT_PROMPT)
        PROPERTY_INFO_ENTRY(INIT_PROVIDERSTRING)
        PROPERTY_INFO_ENTRY(INIT_TIMEOUT)
    END_PROPERTY_SET(DBPROPSET_DBINIT)
    CHAIN_PROPERTY_SET(CCustomSession)
    CHAIN_PROPERTY_SET(CCustomCommand)
END_PROPSET_MAP()

CHAIN_PROPERTY_SET

Essa macro encadeia grupos de propriedades.

Sintaxe

CHAIN_PROPERTY_SET(ChainClass)

Parâmetros

ChainClass
[in] O nome da classe para a qual encadear as propriedades. Essa é uma classe gerada pelo Assistente de Projeto da ATL que já contém um mapa (como uma classe de objeto de sessão, comando ou fonte de dados).

Comentários

Você pode encadear um conjunto de propriedade definida de outra classe para sua própria classe e, em seguida, acessar as propriedades diretamente de sua classe.

Cuidado

Use esta macro com moderação. O uso inadequado pode fazer com que um consumidor falhe nos testes de conformidade do OLE DB.

END_PROPERTY_SET

Marca o final de um conjunto de propriedades.

Sintaxe

END_PROPERTY_SET(guid)

Parâmetros

guid
[in] O nome do GUID.

Exemplo

Confira BEGIN_PROPSET_MAP.

END_PROPSET_MAP

Marca o fim das entradas de mapa do conjunto de propriedades.

Sintaxe

END_PROPSET_MAP()

Exemplo

Confira BEGIN_PROPSET_MAP.

PROPERTY_INFO_ENTRY

Representa uma propriedade específica em um conjunto de propriedades.

Sintaxe

PROPERTY_INFO_ENTRY(dwPropID)

Parâmetros

dwPropID
[in] Um valor DBPROPID que pode ser usado em conjunto com o GUID do conjunto de propriedades para identificar uma propriedade.

Comentários

Essa macro define o valor da propriedade de tipo DWORD como um valor padrão definido em ATLDB.H. Para definir a propriedade como um valor de sua escolha, use PROPERTY_INFO_ENTRY_VALUE. Para definir a VARTYPE e DBPROPFLAGS para a propriedade ao mesmo tempo, use PROPERTY_INFO_ENTRY_EX.

Exemplo

Confira BEGIN_PROPSET_MAP.

PROPERTY_INFO_ENTRY_EX

Representa uma propriedade específica em um conjunto de propriedades.

Sintaxe

PROPERTY_INFO_ENTRY_EX(dwPropID, vt, dwFlags, value, options)

Parâmetros

dwPropID
[in] Um valor DBPROPID que pode ser usado em conjunto com o GUID do conjunto de propriedades para identificar uma propriedade.

Vt
[in] A VARTYPE desta entrada de propriedade. (Definida em wtypes.h)

dwFlags
[in] Um valor DBPROPFLAGS que descreve essa entrada de propriedade.

value
[in] O valor da propriedade do tipo DWORD.

options
DBPROPOPTIONS_REQUIRED ou DBPROPOPTIONS_SETIFCHEAP. Normalmente, um provedor não precisa definir opções, pois ele é definido pelo consumidor.

Comentários

Com essa macro, você pode especificar diretamente o valor da propriedade do tipo DWORD, bem como as opções e sinalizadores. Para simplesmente definir uma propriedade como um valor padrão definido em ATLDB. H, use PROPERTY_INFO_ENTRY. Para definir uma propriedade como um valor de sua escolha, sem definir opções ou sinalizadores nela, use PROPERTY_INFO_ENTRY_VALUE.

Exemplo

Confira BEGIN_PROPSET_MAP.

PROPERTY_INFO_ENTRY_VALUE

Representa uma propriedade específica em um conjunto de propriedades.

Sintaxe

PROPERTY_INFO_ENTRY_VALUE(dwPropID, value)

Parâmetros

dwPropID
[in] Um valor DBPROPID que pode ser usado em conjunto com o GUID do conjunto de propriedades para identificar uma propriedade.

value
[in] O valor da propriedade do tipo DWORD.

Comentários

Com essa macro, você pode especificar diretamente o valor da propriedade do tipo DWORD. Para definir a propriedade como valor padrão definido em ATLDB. H, use PROPERTY_INFO_ENTRY. Para definir o valor, os sinalizadores e as opções da propriedade, use PROPERTY_INFO_ENTRY_EX.

Exemplo

Confira BEGIN_PROPSET_MAP.

BEGIN_PROVIDER_COLUMN_MAP

Marca o início das entradas do mapa de colunas do provedor.

Sintaxe

BEGIN_PROVIDER_COLUMN_MAP(theClass)

Parâmetros

theClass
[in] O nome da classe à qual este mapa pertence.

Exemplo

Aqui está um mapa de coluna do provedor de exemplo:

BEGIN_PROVIDER_COLUMN_MAP(CCustomWindowsFile)
    PROVIDER_COLUMN_ENTRY("FileAttributes", 1, dwFileAttributes)
    PROVIDER_COLUMN_ENTRY("FileSizeHigh", 2, nFileSizeHigh)
    PROVIDER_COLUMN_ENTRY("FileSizeLow", 3, nFileSizeLow)
    PROVIDER_COLUMN_ENTRY_STR("FileName", 4, cFileName)
    PROVIDER_COLUMN_ENTRY_STR("AltFileName", 5, cAlternateFileName)
END_PROVIDER_COLUMN_MAP()

END_PROVIDER_COLUMN_MAP

Marca o final das entradas do mapa de colunas do provedor.

Sintaxe

END_PROVIDER_COLUMN_MAP()

Exemplo

Consulte BEGIN_PROVIDER_COLUMN_MAP.

PROVIDER_COLUMN_ENTRY

Representa uma coluna específica com suporte do provedor.

Sintaxe

PROVIDER_COLUMN_ENTRY (name, ordinal, member)

Parâmetros

name
[in] O nome da coluna.

ordinal
[in] O número da coluna. A menos que a coluna seja uma coluna Indicador, o número da coluna não deve ser 0.

member
[in] A variável membro em dataClass correspondente à coluna.

PROVIDER_COLUMN_ENTRY_FIXED

Representa uma coluna específica com suporte do provedor.

Sintaxe

PROVIDER_COLUMN_ENTRY_FIXED(name, ordinal, dbtype, member)

Parâmetros

name
[in] O nome da coluna.

ordinal
[in] O número da coluna. A menos que a coluna seja uma coluna Indicador, o número da coluna não deve ser 0.

dbtype
[in] O tipo de dados no DBTYPE.

member
[in] A variável de membro em dataClass que armazena os dados.

Comentários

Permite que você especifique o tipo de dados de coluna.

Exemplo

Consulte BEGIN_PROVIDER_COLUMN_MAP.

PROVIDER_COLUMN_ENTRY_GN

Representa uma coluna específica com suporte do provedor.

Sintaxe

PROVIDER_COLUMN_ENTRY_GN (name, ordinal, flags, colSize, dbtype, precision, scale, guid)

Parâmetros

name
[in] O nome da coluna.

ordinal
[in] O número da coluna. A menos que a coluna seja uma coluna Indicador, o número da coluna não deve ser 0.

sinalizadores
[in] Especifica como os dados são retornados. Consulte a descrição de dwFlags nas Estruturas DBBINDING.

colSize
[in] O tamanho da coluna.

dbtype
[in] Indica o tipo de dados do valor. Consulte a descrição de wType nas Estruturas DBBINDING.

precisão
[in] Indica a precisão a ser usada ao obter dados se dbType for DBTYPE_NUMERIC ou DBTYPE_DECIMAL. Consulte a descrição de bPrecision nas Estruturas DBBINDING.

scale
[in] Indica a escala a ser usada ao obter dados se dbType for DBTYPE_NUMERIC ou DBTYPE_DECIMAL. Consulte a descrição de bScale nas Estruturas DBBINDING.

guid
Um GUID de conjunto de linhas de esquema. Consulte IDBSchemaRowset na Referência do Programador OLE DB para obter uma lista de conjuntos de linhas de esquema e seus GUIDs.

Comentários

Permite especificar o tamanho da coluna, o tipo de dados, a precisão, a escala e o GUID do conjunto de linhas de esquema.

PROVIDER_COLUMN_ENTRY_LENGTH

Representa uma coluna específica com suporte do provedor.

Sintaxe

PROVIDER_COLUMN_ENTRY_LENGTH(name, ordinal, size, member)

Parâmetros

name
[in] O nome da coluna.

ordinal
[in] O número da coluna. A menos que a coluna seja uma coluna Indicador, o número da coluna não deve ser 0.

size
[in] Tamanho da coluna em bytes.

member
[in] A variável de membro que dataClass armazena os dados da coluna.

Comentários

Permite que você especifique o tamanho da coluna.

Exemplo

Consulte BEGIN_PROVIDER_COLUMN_MAP.

PROVIDER_COLUMN_ENTRY_STR

Representa uma coluna específica com suporte do provedor.

Sintaxe

PROVIDER_COLUMN_ENTRY_STR(name, ordinal, member)

Parâmetros

name
[in] O nome da coluna.

ordinal
[in] O número da coluna. A menos que a coluna seja uma coluna Indicador, o número da coluna não deve ser 0.

member
[in] A variável de membro na classe de dados que armazena os dados.

Comentários

Use essa macro quando os dados da coluna forem considerados DBTYPE_STR.

Exemplo

Consulte BEGIN_PROVIDER_COLUMN_MAP.

PROVIDER_COLUMN_ENTRY_TYPE_LENGTH

Representa uma coluna específica com suporte do provedor.

Sintaxe

PROVIDER_COLUMN_ENTRY_TYPE_LENGTH(name, ordinal, dbtype, size, member)

Parâmetros

name
[in] O nome da coluna.

ordinal
[in] O número da coluna. A menos que a coluna seja uma coluna Indicador, o número da coluna não deve ser 0.

dbtype
[in] O tipo de dados no DBTYPE.

size
[in] Tamanho da coluna em bytes.

member
[in] A variável de membro na classe de dados que armazena os dados.

Comentários

Semelhante a PROVIDER_COLUMN_ENTRY_LENGTH, mas também permite que você especifique o tipo de dados da coluna, bem como o tamanho.

PROVIDER_COLUMN_ENTRY_WSTR

Representa uma coluna específica com suporte do provedor.

Sintaxe

PROVIDER_COLUMN_ENTRY_WSTR(name, ordinal, member)

Parâmetros

name
[in] O nome da coluna.

ordinal
[in] O número da coluna. A menos que a coluna seja uma coluna Indicador, o número da coluna não deve ser 0.

member
[in] A variável de membro na classe de dados que armazena os dados.

Comentários

Use essa macro quando os dados da coluna forem uma cadeia de caracteres Unicode terminada em nulo, DBTYPE_WSTR.

BEGIN_SCHEMA_MAP

Denota o início de um mapa de esquema.

Sintaxe

BEGIN_SCHEMA_MAP(SchemaClass);

Parâmetros

SchemaClass
A classe que contém o MAPA. Normalmente, essa será a classe de sessão.

Comentários

Consulte IDBSchemaRowset no SDK do Windows para obter mais informações sobre conjuntos de linhas de esquema.

END_SCHEMA_MAP

Denota o final do mapa de esquema.

Sintaxe

END_SCHEMA_MAP()

Comentários

Para obter mais informações, consulte Classe IDBSchemaRowsetImpl.

SCHEMA_ENTRY

Associa um GUID a uma classe.

Sintaxe

SCHEMA_ENTRY(guid,
   rowsetClass);

Parâmetros

guid
Um GUID de conjunto de linhas de esquema. Consulte IDBSchemaRowset na Referência do Programador OLE DB para obter uma lista de conjuntos de linhas de esquema e seus GUIDs.

rowsetClass
A classe que será criada para representar o conjunto de linhas de esquema.

Comentários

IDBSchemaRowsetImpl pode consultar o mapa para obter uma lista de GUIDs ou pode criar um conjunto de linhas se receber um GUID. O conjunto de linhas de esquema IDBSchemaRowsetImpl é semelhante a uma classe padrão derivada de CRowsetImpl, exceto que ele deve fornecer um método Execute que tenha a seguinte assinatura:

HRESULT Execute (LONG* pcRowsAffected,
    ULONG cRestrictions,
    const VARIANT* rgRestrictions);

Essa função Execute preenche os dados do conjunto de linhas. O Assistente de Projeto da ATL cria, conforme descrito no IDBSchemaRowset na Referência do Programador OLE DB, três conjuntos de linhas de esquema iniciais no projeto para cada um dos três esquemas obrigatórios do OLE DB:

DBSCHEMA_TABLES
DBSCHEMA_COLUMNS
DBSCHEMA_PROVIDER_TYPES

O assistente também adiciona três entradas correspondentes no mapa do esquema. Consulte Criando um provedor de modelo OLE DB para obter mais informações sobre como usar o assistente para criar um provedor.

Confira também

Modelos de Provedor OLE DB
Arquitetura de modelo do provedor do OLE DB
Criando um provedor do OLE DB
Referência dos modelos de provedor do OLE DB
Macros para modelos de provedor do OLE DB

Partilhar via

Macros para modelos de provedor de banco de dados OLE

Macros de mapa de conjunto de propriedades

Macros de mapa de colunas

Macros de conjunto de linhas de esquema

Requisitos

BEGIN_PROPERTY_SET

Sintaxe

Parâmetros

Exemplo

BEGIN_PROPERTY_SET_EX

Sintaxe

Parâmetros

Exemplo

BEGIN_PROPSET_MAP

Sintaxe

Parâmetros

Exemplo

CHAIN_PROPERTY_SET

Sintaxe

Parâmetros

Comentários

END_PROPERTY_SET

Sintaxe

Parâmetros

Exemplo

END_PROPSET_MAP

Sintaxe

Exemplo

PROPERTY_INFO_ENTRY

Sintaxe

Parâmetros

Comentários

Exemplo

PROPERTY_INFO_ENTRY_EX

Sintaxe

Parâmetros

Comentários

Exemplo

PROPERTY_INFO_ENTRY_VALUE

Sintaxe

Parâmetros

Comentários

Exemplo

BEGIN_PROVIDER_COLUMN_MAP

Sintaxe

Parâmetros

Exemplo

END_PROVIDER_COLUMN_MAP

Sintaxe

Exemplo

PROVIDER_COLUMN_ENTRY

Sintaxe

Parâmetros

PROVIDER_COLUMN_ENTRY_FIXED

Sintaxe

Parâmetros

Comentários

Exemplo

PROVIDER_COLUMN_ENTRY_GN

Sintaxe

Parâmetros

Comentários

PROVIDER_COLUMN_ENTRY_LENGTH

Sintaxe

Parâmetros

Comentários

Exemplo

PROVIDER_COLUMN_ENTRY_STR

Sintaxe

Parâmetros

Comentários

Exemplo

PROVIDER_COLUMN_ENTRY_TYPE_LENGTH

Sintaxe

Parâmetros

Comentários

PROVIDER_COLUMN_ENTRY_WSTR

Sintaxe

Parâmetros