ATL OLE DB Consumer Wizard

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at ATL OLE DB Consumer Wizard.

This wizard sets up an OLE DB consumer class with the data bindings necessary to access the specified data source through the specified OLE DB provider.

UIElement List

Data Source
The Data Source button lets you set up the specified data source using the specified OLE DB provider. When you click this button, the Data Link Properties dialog box appears. For more information on building connection strings and the Data Link Properties dialog box, see Data Link API Overview in the Windows SDK documentation.

The dialog box has four tabs:

• Provider tab

• Connection tab

• Advanced tab

• All tab

  The following additional information describes the tabs in the Data Link Properties dialog box.

  Click OK to finish. The Select Database Object dialog box appears. From this dialog box, select the table, view, or stored procedure that the consumer will use.

Provider
Select an appropriate provider to manage the connection to the data source. The type of provider is typically determined by the type of database to which you are connecting. Click the Next button or click the Connection tab.

Connection
The contents of this tab depend on the provider you selected. Although there are many types of providers, this section covers connections for the two most common: SQL and ODBC data. The others are similar variations on the fields described here.

 For SQL data:  

1. **Select or enter a server name:** Click the drop-down list menu to display all registered data servers on the network, and select one.  

2. **Enter information to log on to the server:** Enter a user name and password to log on to the data server.  

3. **Select the database on the server:** Click the drop-down list menu to display all registered databases on the data server, and select one.  

     -or-  

Attach a database file as a database name: Specify a file to be used as the database; enter the explicit pathname.

    > [!NOTE]
    >  There is a security problem with the "Allow saving of password" feature of the Data Link Properties dialog box. In "Enter information to log on to the server," there are two radio buttons:  

Use Windows NT integrated security

Use a specific user name and password

     If you select **Use a specific user name and password**, you have the option of saving the password (using the check box for "Allow saving password"); however, this option is not secure. It is recommended that you select **Use Windows NT integrated security**; this option is secure because it encrypts the password.  

     There might be situations in which you want to select "Allow saving password." For example, if you are releasing a library with a private database solution, you should not access the database directly but instead use a middle-tier application to verify the user (through whatever authentication scheme you choose) and then limit the sort of data available to the user.  

     For ODBC data:  

     1. **Specify the source of data:** You can use a data source name or a connection string.  

Use data source name: This drop-down list displays data sources registered in your machine. You can set up data sources ahead of time using the ODBC Data Source Administrator-or-Use connection string: Either enter a connection string you have already obtained, or click the Build button; the Select Data Source dialog box appears. Select a file or machine data source and click OK.

    > [!NOTE]
    >  You can obtain a connection string by viewing the properties of an existing connection in Server Explorer, or you can create a connection by double-clicking **Add Connection** in Server Explorer.  

     2. **Enter information to log on to the server:** Enter a user name and password to log on to the data server.  

     3. Enter the initial catalog to use.  

     4. Click **Test Connection**; if the test succeeds, click **OK**. If not, check your logon information, try another database, or try another data server.  

Advanced
Network settings: Specify the Impersonation level (the level of impersonation that the server is allowed to use when impersonating the client; corresponds directly to RPC impersonation levels) and Protection level (the level of protection of data sent between client and server; corresponds directly to RPC protection levels).

Other: In Connect timeout, specify the number of seconds of idle time allowed before a timeout occurs. In Access permissions, specify the access permissions on the data connection.

 For more information about advanced initialization properties, refer to the documentation provided with each specific OLE DB provider.  

All
This tab displays a summary of the initialization properties for the data source and connection you have specified. You can edit these values.

 Click **OK** to finish. The **Select Database Object** dialog box appears. From this dialog box, select the table, view, or stored procedure that the consumer will use.  

Class
After you select a data source, this box is populated with a default class name based on the table or stored procedure that you selected (see Select a data source below). You can edit the class name.

.h file
After you select a data source, this box is populated with a default header class name based on the table or stored procedure that you selected (see Select a data source below). You can edit the header file's name or select an existing header file.

Attributed
This option specifies whether the wizard will create consumer classes using attributes or template declarations. When you select this option, the wizard uses attributes instead of template declarations (this is the default option). When you deselect this option, the wizard uses template declarations instead of attributes.

• If you select a consumer Type of Table, the wizard uses the db_source and db_table attributes to create the table and table accessor class declarations, and uses db_column to create the column map, for example:

[  
   db_source("<initialization_string>"), 
   db_table("dbo.Orders") 
]  
... *// Column map  
[ db_column(1, status=m_dwOrderIDStatus,      length=m_dwOrderIDLength) ] LONG m_OrderID;  
[ db_column(2, status=m_dwCustomerIDStatus,      length=m_dwCustomerIDLength) ] TCHAR m_CustomerID[6];  
...  

 instead of using the `CTable` template class to declare the table and table accessor class, and the BEGIN_COLUMN_MAP and END_COLUMN_MAP macros to create the column map, for example:  

   class COrdersAccessor; *// Table class  
   class COrders : public CTable<CAccessor<COrdersAccessor>>;  
... *// Column map  
   BEGIN_COLUMN_MAP(COrderDetailsAccessor) 
   COLUMN_ENTRY_LENGTH_STATUS(1, m_OrderID,      m_dwOrderIDLength, m_dwOrderIDStatus)  
   COLUMN_ENTRY_LENGTH_STATUS(2, m_CustomerID,      m_dwCustomerIDLength, m_dwCustomerIDStatus)  
...  
   END_COLUMN_MAP() 

• If you select a consumer Type of Command, the wizard uses the db_source and db_command attributes, and uses db_column to create the column map, for example:

[  
   db_source
("<initialization_string>"), 
   db_command
("SQL_command") 
]  
... *// Column map using db_column is the same as for consumer type of 'table'  

 instead of using the command and command accessor class declarations in the command class' .h file, for example:  

   Command accessor class:  
   class CListOrdersAccessor;  
   Command class:  
   class CListOrders : public CCommand<CAccessor<CListOrdersAccessor>>;  
... *// Column map using BEGIN_COLUMN_MAP ... END_COLUMN_MAP is the same as *// for consumer type of 'table'  

See Basic Mechanics of Attributes for more information.

Type
Select one of these radio buttons to specify whether the consumer class will be derived from CTable or CCommand (default).

Table
Select this option if you want to use CTable or db_table to create the table and table accessor class declarations.

Command
Select this option if you want to use CCommand or db_command to create the command and command accessor class declarations. This is the default selection.

Support
Select the check boxes to specify the kinds of updates to be supported in the consumer (the default is none). Each of the following will set DBPROP_IRowsetChange and the appropriate entries for DBPROP_UPDATABILITY in the property set map.

Change
Specifies that the consumer support updates of row data in the rowset.

Insert
Specifies that the consumer support insertion of rows into the rowset.

Delete
Specifies that the consumer support deletion of rows from the rowset.

See Also

ATL OLE DB Consumer
Adding Functionality with Code Wizards
Connection Strings and Data Links (OLE DB)