Macros for OLE DB Provider Templates

Article
08/03/2021

The OLE DB Templates Provider macros offer functionality in the following categories:

Property Set Map Macros

Name	Description
BEGIN_PROPERTY_SET	Marks the beginning of a property set.
BEGIN_PROPERTY_SET_EX	Marks the beginning of a property set.
BEGIN_PROPSET_MAP	Marks the beginning of a property set that can be hidden or defined outside the scope of the provider.
CHAIN_PROPERTY_SET	Chains property groups together.
END_PROPERTY_SET	Marks the end of a property set.
END_PROPSET_MAP	Marks the end of a property set map.
PROPERTY_INFO_ENTRY	Sets a specific property in a property set to a default value.
PROPERTY_INFO_ENTRY_EX	Sets a specific property in a property set to a value supplied by you. Also enables you to set flags and options.
PROPERTY_INFO_ENTRY_VALUE	Sets a specific property in a property set to a value supplied by you.

Column Map Macros

Name	Description
BEGIN_PROVIDER_COLUMN_MAP	Marks the beginning of the provider column map entries.
END_PROVIDER_COLUMN_MAP	Marks the end of the provider column map entries.
PROVIDER_COLUMN_ENTRY	Represents a specific column supported by the provider.
PROVIDER_COLUMN_ENTRY_FIXED	Represents a specific column supported by the provider. You can specify the column data type.
PROVIDER_COLUMN_ENTRY_GN	Represents a specific column supported by the provider. You can specify the column's size, data type, precision, scale, and schema rowset GUID.
PROVIDER_COLUMN_ENTRY_LENGTH	Represents a specific column supported by the provider. You can specify the column size.
PROVIDER_COLUMN_ENTRY_STR	Represents a specific column supported by the provider. It assumes the column type is a string.
PROVIDER_COLUMN_ENTRY_TYPE_LENGTH	Represents a specific column supported by the provider. Like PROVIDER_COLUMN_ENTRY_LENGTH, but also allows you to specify the column's data type as well as size.
PROVIDER_COLUMN_ENTRY_WSTR	Represents a specific column supported by the provider. It assumes the column type is a Unicode character string.

Schema Rowset Macros

Name	Description
BEGIN_SCHEMA_MAP	Marks the beginning of a schema map.
END_SCHEMA_MAP	Marks the end of a schema map.
SCHEMA_ENTRY	Associates a GUID with a class.

Requirements

Header: atldb.h

BEGIN_PROPERTY_SET

Marks the beginning of a property set in a property set map.

Syntax

BEGIN_PROPERTY_SET(guid)

Parameters

guid
[in] The property GUID.

Example

See BEGIN_PROPSET_MAP.

BEGIN_PROPERTY_SET_EX

Marks the beginning of a property set in a property set map.

Syntax

BEGIN_PROPERTY_SET_EX(guid, flags)

Parameters

guid
[in] The property GUID.

flags
[in] UPROPSET_HIDDEN for any property sets you do not wish to expose, or UPROPSET_PASSTHROUGH for a provider exposing properties defined outside the scope of the provider.

Example

See BEGIN_PROPSET_MAP.

BEGIN_PROPSET_MAP

Marks the beginning of the property set map entries.

Syntax

BEGIN_PROPSET_MAP(Class)

Parameters

Class
[in] The class in which this property set is specified. A property set can be specified in the following OLE DB objects:

Example

Here is a sample property set map:

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

This macro chains property groups together.

Syntax

CHAIN_PROPERTY_SET(ChainClass)

Parameters

ChainClass
[in] The name of the class to chain properties for. This is a class generated by the ATL Project Wizard that already contains a map (such as a session, command, or data source object class).

Remarks

You can chain a property set from another class to your own class, then access the properties directly from your class.

Caution

Use this macro sparingly. Improper use can cause a consumer to fail the OLE DB conformance tests.

END_PROPERTY_SET

Marks the end of a property set.

Syntax

END_PROPERTY_SET(guid)

Parameters

guid
[in] The property GUID.

Example

See BEGIN_PROPSET_MAP.

END_PROPSET_MAP

Marks the end of property set map entries.

Syntax

END_PROPSET_MAP()

Example

See BEGIN_PROPSET_MAP.

PROPERTY_INFO_ENTRY

Represents a specific property in a property set.

Syntax

PROPERTY_INFO_ENTRY(dwPropID)

Parameters

dwPropID
[in] A DBPROPID value that can be used in conjunction with the property set GUID to identify a property.

Remarks

This macro sets the property value of type DWORD to a default value defined in ATLDB.H. To set the property to a value of your choosing, use PROPERTY_INFO_ENTRY_VALUE. To set the VARTYPE and DBPROPFLAGS for the property at the same time, use PROPERTY_INFO_ENTRY_EX.

Example

See BEGIN_PROPSET_MAP.

PROPERTY_INFO_ENTRY_EX

Represents a specific property in a property set.

Syntax

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

Parameters

dwPropID
[in] A DBPROPID value that can be used in conjunction with the property set GUID to identify a property.

vt
[in] The VARTYPE of this property entry. (Defined in wtypes.h)

dwFlags
[in] A DBPROPFLAGS value describing this property entry.

value
[in] The property value of type DWORD.

options
Either DBPROPOPTIONS_REQUIRED or DBPROPOPTIONS_SETIFCHEAP. Normally, a provider does not need to set options since it is set by the consumer.

Remarks

With this macro, you can directly specify the property value of type DWORD as well as options and flags. To merely set a property to a default value defined in ATLDB.H, use PROPERTY_INFO_ENTRY. To set a property to a value of your choice, without setting options or flags on it, use PROPERTY_INFO_ENTRY_VALUE.

Example

See BEGIN_PROPSET_MAP.

PROPERTY_INFO_ENTRY_VALUE

Represents a specific property in a property set.

Syntax

PROPERTY_INFO_ENTRY_VALUE(dwPropID, value)

Parameters

dwPropID
[in] A DBPROPID value that can be used in conjunction with the property set GUID to identify a property.

value
[in] The property value of type DWORD.

Remarks

With this macro, you can directly specify the property value of type DWORD. To set the property to default value defined in ATLDB.H, use PROPERTY_INFO_ENTRY. To set the value, flags, and options for the property, use PROPERTY_INFO_ENTRY_EX.

Example

See BEGIN_PROPSET_MAP.

BEGIN_PROVIDER_COLUMN_MAP

Marks the beginning of the provider column map entries.

Syntax

BEGIN_PROVIDER_COLUMN_MAP(theClass)

Parameters

theClass
[in] The name of the class this map belongs to.

Example

Here is a sample provider column map:

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

Marks the end of the provider column map entries.

Syntax

END_PROVIDER_COLUMN_MAP()

Example

See BEGIN_PROVIDER_COLUMN_MAP.

PROVIDER_COLUMN_ENTRY

Represents a specific column supported by the provider.

Syntax

PROVIDER_COLUMN_ENTRY (name, ordinal, member)

Parameters

name
[in] The column name.

ordinal
[in] The column number. Unless the column is a Bookmark column, the column number must not be 0.

member
[in] The member variable in dataClass corresponding to the column.

PROVIDER_COLUMN_ENTRY_FIXED

Represents a specific column supported by the provider.

Syntax

PROVIDER_COLUMN_ENTRY_FIXED(name, ordinal, dbtype, member)

Parameters

name
[in] The column name.

ordinal
[in] The column number. Unless the column is a Bookmark column, the column number must not be 0.

dbtype
[in] The data type in DBTYPE.

member
[in] The member variable in dataClass that stores the data.

Remarks

Allows you to specify the column data type.

Example

See BEGIN_PROVIDER_COLUMN_MAP.

PROVIDER_COLUMN_ENTRY_GN

Represents a specific column supported by the provider.

Syntax

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

Parameters

name
[in] The column name.

ordinal
[in] The column number. Unless the column is a Bookmark column, the column number must not be 0.

flags
[in] Specifies how data is returned. See the dwFlags description in DBBINDING Structures.

colSize
[in] The column size.

dbtype
[in] Indicates the data type of the value. See the wType description in DBBINDING Structures.

precision
[in] Indicates the precision to use when getting data if dbType is DBTYPE_NUMERIC or DBTYPE_DECIMAL. See the bPrecision description in DBBINDING Structures.

scale
[in] Indicates the scale to use when getting data if dbType is DBTYPE_NUMERIC or DBTYPE_DECIMAL. See the bScale description in DBBINDING Structures.

guid
A schema rowset GUID. See IDBSchemaRowset in the OLE DB Programmer's Reference for a list of schema rowsets and their GUIDs.

Remarks

Allows you to specify the column's size, data type, precision, scale, and schema rowset GUID.

PROVIDER_COLUMN_ENTRY_LENGTH

Represents a specific column supported by the provider.

Syntax

PROVIDER_COLUMN_ENTRY_LENGTH(name, ordinal, size, member)

Parameters

name
[in] The column name.

ordinal
[in] The column number. Unless the column is a Bookmark column, the column number must not be 0.

size
[in] The column size in bytes.

member
[in] The member variable in dataClass that stores the column data.

Remarks

Allows you to specify the column size.

Example

See BEGIN_PROVIDER_COLUMN_MAP.

PROVIDER_COLUMN_ENTRY_STR

Represents a specific column supported by the provider.

Syntax

PROVIDER_COLUMN_ENTRY_STR(name, ordinal, member)

Parameters

name
[in] The column name.

ordinal
[in] The column number. Unless the column is a Bookmark column, the column number must not be 0.

member
[in] The member variable in the data class that stores the data.

Remarks

Use this macro when the column data is assumed to be DBTYPE_STR.

Example

See BEGIN_PROVIDER_COLUMN_MAP.

PROVIDER_COLUMN_ENTRY_TYPE_LENGTH

Represents a specific column supported by the provider.

Syntax

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

Parameters

name
[in] The column name.

ordinal
[in] The column number. Unless the column is a Bookmark column, the column number must not be 0.

dbtype
[in] The data type in DBTYPE.

size
[in] The column size in bytes.

member
[in] The member variable in the data class that stores the data.

Remarks

Similar to PROVIDER_COLUMN_ENTRY_LENGTH but also allows you to specify the column's data type as well as size.

PROVIDER_COLUMN_ENTRY_WSTR

Represents a specific column supported by the provider.

Syntax

PROVIDER_COLUMN_ENTRY_WSTR(name, ordinal, member)

Parameters

name
[in] The column name.

ordinal
[in] The column number. Unless the column is a Bookmark column, the column number must not be 0.

member
[in] The member variable in the data class that stores the data.

Remarks

Use this macro when the column data is a null terminated Unicode character string, DBTYPE_WSTR.

BEGIN_SCHEMA_MAP

Denotes the beginning of a schema map.

Syntax

BEGIN_SCHEMA_MAP(SchemaClass);

Parameters

SchemaClass
The class that contains the MAP. Typically this will be the session class.

Remarks

See IDBSchemaRowset in the Windows SDK for more information about schema rowsets.

END_SCHEMA_MAP

Denotes the end of the schema map.

Syntax

END_SCHEMA_MAP()

Remarks

For more information, see IDBSchemaRowsetImpl Class.

SCHEMA_ENTRY

Associates a GUID with a class.

Syntax

SCHEMA_ENTRY(guid,
   rowsetClass);

Parameters

guid
A schema rowset GUID. See IDBSchemaRowset in the OLE DB Programmer's Reference for a list of schema rowsets and their GUIDs.

rowsetClass
The class that will be created to represent the schema rowset.

Remarks

IDBSchemaRowsetImpl can then query the map for a list of GUIDs, or it can create a rowset if it is given a GUID. The schema rowset IDBSchemaRowsetImpl creates is similar to a standard CRowsetImpl-derived class, except it must provide an Execute method that has the following signature:

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

This Execute function populates the rowset's data. The ATL Project Wizard creates, as described in IDBSchemaRowset in the OLE DB Programmer's Reference, three initial schema rowsets in the project for each of the three mandatory OLE DB schemas:

DBSCHEMA_TABLES
DBSCHEMA_COLUMNS
DBSCHEMA_PROVIDER_TYPES

The wizard also adds three corresponding entries in the schema map. See Creating an OLE DB Template Provider for more information about using the wizard to create a provider.