DOCUMENT:Q249829 26-MAY-2002 [visualc] TITLE :Add Custom Properties to an ATL OLE DB Provider PRODUCT :Microsoft C Compiler PROD/VER::6.0 OPER/SYS: KEYWORDS:kbfile kbATL kbDatabase kbDTL kbOLEDB kbProvider kbVC kbGrpDSVCDB kbMDACNoSweep ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual C++, 32-bit Enterprise Edition, version 6.0 - Microsoft Visual C++, 32-bit Professional Edition, version 6.0 - Microsoft Visual C++, 32-bit Learning Edition, version 6.0 ------------------------------------------------------------------------------- SUMMARY ======= This article describes the steps necessary to add customer properties to an ATL OLE DB provider. Furthermore, this article contains revised code for the Atldb.h ATL header file that is necessary to expose custom datasource and rowset properties. MORE INFORMATION ================ Custom OLE DB properties are necessary when a provider needs to expose provider-specific behaviors and attributes. For example, the Microsoft Jet Database OLE DB Provider exposes custom properties for setting specific behaviors such as the Jet cache maximum buffer size. To add custom properties to a provider that is built using the ATL OLE DB Provider Template classes, perform the following steps: 1. Run the GUIDGEN utility which comes with Visual C++ and when the tool appears, select static const struct GUID and then click Copy. This copies a declaration into the clipboard which you can then paste into your provider code. This becomes the GUID for the property set which contains the custom property. Thus, for instance, add the following line of code to the datasource header file: // {9AD18F30-C1DE-11d3-918F-0090275A5E01} static const GUID DBPROPSET_MYPROPERTIES = { 0x9ad18f30, 0xc1de, 0x11d3, { 0x91, 0x8f, 0x0, 0x90, 0x27, 0x5a, 0x5e, 0x1 } }; 2. After defining the GUID for the custom property set, you must define an ID for the custom property. For instance, at the top of the datasource header file, you can also have something like the following code: #define DBPROP_MYPROP 1 Add the property and property set into the provider using the PROPERTY_INFO_ENTRY_EX macro. The property map for your provider may look like this: BEGIN_PROPSET_MAP(CATLCustomPropsSource) 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) // Add custom property set - it contains one initialization property BEGIN_PROPERTY_SET(DBPROPSET_MYPROPERTIES) PROPERTY_INFO_ENTRY_EX(MYPROP, VT_BSTR, DBPROPFLAGS_DBINIT | DBPROPFLAGS_READ | DBPROPFLAGS_WRITE, L"Some value", DBPROPOPTIONS_OPTIONAL) END_PROPERTY_SET(DBPROPSET_MYPROPERTIES) CHAIN_PROPERTY_SET(CATLCustomPropsCommand) END_PROPSET_MAP() 3. Add a string resource for the property into the string table in the .rc file. The string resource is the description for the property such as "My Datasouce Property". The constant for the string resource would be IDS_DBPROP_MYPROP. This is the constant of the customer property (DBPROP_MYPROP) prepended with "IDS_". 4. Lastly, you'll need to make changes to the Atldb.h file. The following functions must be revised in the Atldb.h file to expose these newly added custom properties from the datasource object: IDBPropertiesImpl::GetProperties() IDBPropertiesImpl::SetProperties() CUtlPropInfo::GetPropertyInfo() To expose custom rowset properties, you need to revise IRowsetInfoImpl::GetProperties(). The Atldb.h implementation for the functions call CUtlProps::GetProperties() passing in an array of GUIDs which restrict the properties to known property sets such as DBPROPSET_DBINIT instead of allowing for the getting and setting of all initialization properties including custom properties. This article contains a Visual C++ sample which contains a project for the ATL OLE DB Provider, a revised Atldb.h header created by using the Atldb.h file from Visual Studio 6.0 Service Pack 3 and revising the functions listed above, and a client Visual C++ ADO application that gets the values of the custom properties from the datasource and rowset objects of the provider. The self-extracting .exe file places all of the files into the root folder with a subfolder called ADO client which contains the code for the Visual C++ ADO client which demonstrates getting the custom properties. You can see a revised copy of the Atldb.h file that can be copied from or used as a replacement for the header file which is included with Visual Studio 6.0 Service Pack 3. Look in the ATLCustomPropsDS.h, ATLCustomPropsRS.h, and the .rc file to see the implementation of the steps described earlier in this article. The following file is available for download from the Microsoft Download Center: CustProp.exe Release Date: Jan-03-2000 For additional information about how to download Microsoft Support files, click the article number below to view the article in the Microsoft Knowledge Base: Q119591 How to Obtain Microsoft Support Files from Online Services Microsoft used the most current virus detection software available on the date of posting to scan this file for viruses. After it is posted, the file is housed on secure servers that prevent any unauthorized changes to the file. REFERENCES ========== For more information about OLE DB properties and property sets, see chapter 11 of the OLE DB Programmer's Reference on the Microsoft Developer Network CD. Additional query words: ====================================================================== Keywords : kbfile kbATL kbDatabase kbDTL kbOLEDB kbProvider kbVC kbGrpDSVCDB kbMDACNoSweep Technology : kbVCsearch kbAudDeveloper kbVC600 kbVC32bitSearch Version : :6.0 Issue type : kbhowto ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 2002.