Chapter 8: Developing Database Applications with ADO 259 delivered as part of the SQL Server 2000 client components. ADO was delivered as part of the Visual Basic 6.0 and the older pre- .NET Visual Studio Enterprise Edition, which included Visual Basic 6.0 and Visual C++ 6.0. ADO has since been succeeded by ADO.NET and Visual Studio 2005, which you can read about in Chapter 7. However, there are still many COM-based ADO applications written in Visual Basic 6.0 that connect to SQL Server. As you saw in Figure 8-2, OLE DB provides two distinctly different methods for accessing SQL Server data: the OLE DB for SQL Server provider and the OLE DB provider for ODBC. ADO can work with both of these OLE DB providers. ADO takes advantage of a multilevel architecture that insulates the applications using the ADO object framework from the underlying network protocols and topology. Figure 8-3 illustrates the relationship of ADO, OLE DB, ODBC, and the PCs networking support. At the top of the figure, you can see the Visual Basic ADO application. The Visual Basic application creates and uses the various ADO objects. The ADO object framework makes calls to the appropriate OLE DB provider. If the ADO application is using the OLE DB provider for ODBC, then the MSDASQL OLE DB provider will be used. If the ADO application is using the OLE DB for SQL Server provider, then the SQLOLEDB provider will be used. When using the OLE DB provider for ODBC, ADO loads the msdasql.dll file, which, in turn, loads the ODBC Driver Manager. The OLE DB provider for ODBC maps the OLE DB calls made by ADO into ODBC calls, which are passed on to the ODBC Driver Manager. Figure 8-3 ADO Network architecture 260 Microsoft SQL Server 2005 Developer’s Guide The ODBC Driver Manager handles loading the appropriate ODBC driver. The ODBC driver typically uses a network interprocess communication (IPC) method like Named Pipes, TCP/IP Sockets, or SPX to communicate to a remote IPC server that provides access to the target database. The native OLE DB provider for SQL Server doesn’t use any additional middle layers. When using the OLE DB provider for SQL Server, ADO loads sqloledb.dll, which directly loads and uses the appropriate network IPC method to communicate with the database. The IPC client component establishes a communications link with the corresponding server IPC through the networking protocol in use. The network protocol is responsible for sending and receiving the IPC data stream over the network. The most common network protocol is TCP/IP. Finally, at the bottom of this stack is the physical network topology. The physical network includes the adapter cards and cabling that make the actual connections between the networked systems. Ethernet is the most common network topology. OLE DB and ADO Files Here is a summary of the client files used to implement ADO: File Description msdasql.dll OLE DB Provider for ODBC Sqloledb.dll OLE DB Provider for SQL Server msado15.dll ADO Object Library ADO Architecture As with several of the other data access object models, ADO is implemented using a hierarchical object framework. However, the ADO object model is simpler and flatter than Microsoft’s previous data access object libraries, such as Data Access Objects (DAO) or Remote Database Objects (RDO) frameworks. In Figure 8-4, you can see an overview of ADO’s object hierarchy. The Connection, Recordset, and Command objects are the three primary objects in the ADO object model. The Connection object represents a connection to the remote data source. In addition to establishing the connection to a data source, Chapter 8: Developing Database Applications with ADO 261 Connection objects can also be used to control the transaction scope. A Connection object can be associated with either a Recordset object or a Command object. The Recordset object represents a result set returned from the data source. An ADO Recordset object can either use an open Connection object or establish its own connection to the target data source. Recordset objects let you both query and modify data. Each Recordset object contains a collection of Field objects, where each Field object represents a column of data in the Recordset. The Command object is used to issue commands and parameterized SQL statements. Command objects can be used to call stored procedures and execute SQL action statements, as well as SQL queries that return recordsets. Like the ADO Recordset object, the Command object can either use an active Connection object or establish its own connection to the target data source. The Command object contains a Parameters ADO Application Errors Error Command Parameters Parameter Recordset Fields Field Fields Field Stream Record Connection Figure 8-4 ADO object hierarchy 262 Microsoft SQL Server 2005 Developer’s Guide collection, where each Parameter object in the collection represents a parameter the Command object uses. In the case where a Command object executes a parameterized SQL statement, each Parameter object would represent one of the parameters in the SQL statement. Directly beneath the Connection object is the Errors collection. Each Error object contained in the Errors collection contains information about an error encountered by one of the objects in the ADO object framework. In addition to the main objects shown in Figure 8-4, the Connection, Command, Recordset, and Field objects all have a Properties collection, which consists of a set of Property objects. Each Property object can be used to get or set the various properties associated with the object. While the Connection, Command, and Recordset objects are the most commonly used objects in the ADO object framework, ADO also includes Record and Stream objects. The Record object can be used to represent a single record in a Recordset, or it can represent hierarchical tree-structured namespaces. The Record object can be used to represent hierarchically structured entities like folders and files in a file system, or directories and messages in an e-mail system. The Stream object is used to read or write stream-oriented data such as XML documents or binary objects. While at first glance, the ADO framework may seem as hierarchically structured as DAO and RDO, that’s not really the case. Unlike the older data access object frameworks that ADO essentially replaces, all the primary ADO objects (for example, Connection, Command, and Recordset) can be created on their own without needing to be accessed through a higher-level object. This makes the ADO object framework much flatter and more flexible than the other object models. For instance, the ADO object framework allows a Recordset object to be opened and accessed without first requiring an instance of the Connection object. The capability to use each object directly without first instantiating any higher-order objects tends to make ADO a bit simpler to work with than the other object frameworks. As you see in some of the code examples, however, ADO isn’t always as straightforward in use as the other frameworks. An Overview of Using ADO ADO is built as a COM automation server, which makes accessing ADO functions from Visual Basic easier. Unlike when using ODBC or other DLL-based APIs, where you must manually declare their functions and parameters in a .bas or .cls module, with ADO you only need to add the ADO reference to your project, as explained in the next section. After adding the ADO reference to your Visual Basic Chapter 8: Developing Database Applications with ADO 263 development environment, you can readily use all the ADO objects. A summary of the steps required to use ADO from Visual Basic follows: 1. Make a reference in Visual Basic to the Microsoft ADO 2.8 object library. 2. Open a connection using the Connection, Command, or Recordset object. 3. Use the Command or Recordset object to access data. 4. Close the connection to the Connection, Command, or Recordset object. Adding the ADO Reference to Visual Basic Before you can use ADO from Visual Basic, you must set a reference to the ADO object library, also known as the ADO automation server. The files that provide the basic support for ADO 2.8 are installed on the system when you first download the ADO support from the Microsoft Web site or when you install one of the products containing ADO listed previously, in the section “ADO (ActiveX Data Objects).” Before you can begin using ADO in your Visual Basic projects, however, you need to set a reference to the ADO COM object library in Visual Basic’s development environment. To add a reference to the ADO Objects 2.8 Library in Visual Basic 6, start Visual Basic, and then select Project | References to display the References dialog box shown in Figure 8-5. Figure 8-5 Setting a reference to the ADO Object Library 264 Microsoft SQL Server 2005 Developer’s Guide In the References dialog box, scroll through the Available References list until you see the Microsoft ActiveX Data Objects 2.8 Library option. Clicking the check box and then clicking the OK button adds the ADO Objects Library to Visual Basic’s Interactive Development Environment (IDE). Unlike ActiveX Controls, adding a reference to Visual Basic’s IDE doesn’t create any visual objects in Visual Basic’s Toolbox. To see the ADO objects, properties, and methods, you need to use Visual Basic’s Object Browser. Figure 8-6 displays the ADO Objects Library using Visual Basic’s Object Browser. Using ADO Objects with Visual Basic After adding a reference to the ADO object library in the Visual Basic development environment, you’re ready to create Visual Basic applications using ADO. Unlike the DAO or RDO object models, ADO has no top-level object that must be created Figure 8-6 Viewing the ADO classes from the Object Browser Chapter 8: Developing Database Applications with ADO 265 before you establish a connection to a data source. Using ADO, the first action your application takes is to open a connection using the Connection, Command, or Recordset object. Connecting to SQL Server ADO can connect to SQL Server using either the MSDASQL OLE DB provider for ODBC or the SQLOLEDB OLE DB provider for SQL Server. The MSDASQL provider allows the ADO object framework to be used with existing ODBC drivers, while the SQLOLEDB OLE DB provider connects directly to SQL Server. Both of these OLE DB providers can be used with the ADO Connection, Command, and Recordset objects. In the following section, you see how to establish a connection with SQL Server using both the OLE DB provider for ODBC and the OLE DB provider for SQL Server. You also see how to connect to SQL Server using the ADO Connection object, as well as making a connection directly using ADO Recordset object. Opening a Connection with the OLE DB Provider for ODBC If you’re familiar with the DAO or RDO object frameworks, using the ADO Connection object with the OLE DB provider for ODBC to establish a connection to a SQL Server system is probably the most familiar starting point for beginning to build an ADO application. Like DAO and RDO, the MSDASQL OLE DB provider for ODBC uses an ODBC driver to access SQL Server. This means either the system running the application must have an existing ODBC driver for SQL Server and a Data Source Name (DSN) for SQL Server in the ODBC Administrator, or the application must use a DSN-less connection string. The following code illustrates how to use the ADO Connection object and the MSDASQL provider to prompt the user to select an existing DSN that will be used to connect to SQL Server: Private Sub Connect(sLoginID As String, sPassword As String) Dim cn As New ADODB.Connection ' DSN Connection using the OLE DB provider for ODBC – MSDASQL cn.ConnectionString = "DSN=" & _ ";DATABASE=AdventureWorks;UID=" & sLoginID & _ ";PWD=" & sPassword ' Prompt the user to select the DSN cn.Properties("Prompt") = adPromptComplete cn.Open cn.Close End Sub 266 Microsoft SQL Server 2005 Developer’s Guide In the beginning of this code example, you can see where a new instance of the ADO Connection object named cn is created. Because ADO objects don’t rely on upper-level objects, each object must generally have a Dim statement that uses Visual Basic’s New keyword. Or, you could use late-binding and create the object at run time using the CreateObject statement. Next, the ConnectionString property of the cn Connection object is assigned an ODBC connection string. Like the normal ODBC connection string, the connection string used in the ADO ConnectionString property must contain a set of predefined keywords where each keyword and its associated value are separated from the other keywords and their values by semicolons. Because ADO is based on OLE DB rather than just ODBC, the keywords used in the connection string are a bit different than the keywords used in a standard ODBC connection string. Table 8-1 presents the ADO connection string keywords supported for all OLE DB providers. TIP While this example uses uppercase to present the OLE DB connection string keywords, that isn’t a requirement. The keywords aren’t case-sensitive. In addition to the generic OLE DB connection string keywords, each OLE DB provider also supports provider-specific connection string keywords. In the case of the OLE DB Provider for ODBC, the provider passes on any non-ADO connection Table 8-1 Common ADO Connection String Keywords Keyword Description PROVIDER This optional keyword can be used to identify the name of the OLE DB provider to be used. If no provider name is supplied, the connection uses the MSDASQL provider. DATASOURCE or SERVER The name of an existing SQL Server instance. DATABASE or INITIAL CATALOG The SQL Server target database name. USER ID or UID The login ID for the data source (used for SQL Server authentication). PASSWORD or PWD The password associated with the login ID (used for SQL Server authentication). OLE DB Services Used to disable specific OLE DB services. The value of –1 is the default that indicates all services are enabled; –2 disables connection pooling; –4 disables connection pooling and auto-enlistment; –5 disables client cursors; –6 disables pooling, auto- enlistment, and client cursors; 0 disables all services. Chapter 8: Developing Database Applications with ADO 267 parameters to the ODBC driver manager, which uses them with the target ODBC driver. Table 8-2 lists the connection string keywords supported by MSDASQL, provider for the Microsoft SQL Server ODBC driver. The most common keywords are presented at the top of the list, and the lesser-used keywords follow in alphabetical order. Keyword Description DSN The name of an existing data source created using the ODBC Administrator. FILEDSN The name of an existing file data source created using the ODBC Administrator. DRIVER The name of an existing ODBC driver. SERVER The name of an existing SQL Server system. SAVEFILE The name of a file data source that contains the saved connection information. ADDRESS The network address of the SQL Server system. ANSINPW Uses a value of YES or NO, where YES specifies that ANSI-defined behaviors are to be used for handling NULLs. APP Specifies the name of the client application. ATTACHDBFILENAME Specifies the name of an attachable database. The path to the data file must be included (for example, c:\ mssql\Mydatabase.mdf). If the database was detached, it automatically becomes attached after the connection completes and the database then becomes the default database for the connection. AUTOTRANSLATE Uses a value of TRUE or FALSE, where FALSE prevents automatic ANSI/multibyte character conversions. The default value of TRUE automatically converts the values transfer between SQL server and the client. FALLBACK Uses a value of YES or NO, where YES specifies the ODBC driver should attempt to connect to the fallback server specified by an earlier SQLSetConnectAttr ODBC function call (SQL Server 6.5 only). LANGUAGE Specifies the SQL Server language name to be used for this connection. NETWORK Specifies the network library DLL to be used. The value used by this keyword should not include the path of the .dll file extension. QUERYLOGFILE Specifies the full path of the file used to store query logs. QUERYLOG_ON Uses a value of YES or NO, where YES specifies that long-running queries are to be logged to the query log file specified by the QUERYLOGFILE keyword. QUOTEDID Uses a value of YES or NO, where YES specifies that Quoted Identifiers will be set on for the connection. Table 8-2 OLE DB Provider for ODBC Provider-Specific Keywords for SQL Server 268 Microsoft SQL Server 2005 Developer’s Guide After the OLE DB connection string is assigned to the Connection object’s ConnectionString property, the Connection object’s Prompt property is assigned the constant value of adPromptComplete. This value specifies the ODBC Driver Manager should prompt for any required connection information that’s not supplied in the connection string. TIP The Properties collection of the ADO Connection, Command, and Recordset objects lets you get and set property values using named items in the Properties collection. In fact, some ADO properties like the Prompt property aren’t exposed directly through the object framework and can only be accessed through the Properties collection. While this dynamic Properties collection gives the ADO object model more flexibility than DAO or RDO, it also hides properties, making it more difficult to find and work with properties than the more straightforward DAO or RDO object models. If you can’t find an ADO property you think should exist, try searching for it by iterating through the Properties collection. The Prompt property controls how the ODBC Driver Manager responds to the keyword and values contained in the connection string. Table 8-3 lists the valid values for the Prompt property. In this example, the connection string doesn’t use the PROVIDER keyword, so the OLE DB provider for ODBC—MSDASQL—is used by default. This means the connection to SQL Server takes place via an ODBC driver. In addition, the connection string doesn’t specify a value for the DSN keyword. This means Keyword Description REGIONAL Uses a value of YES or NO, where YES specifies SQL Server uses client settings when converting date, time, currency, and data. STATSLOGFILE Specifies the full path of the file used to store ODBC driver performance statistics. STATSLOG_ON Uses a value of YES or NO, where YES specifies ODBC driver statistics are to be logged to the stats log file specified by the STATSLOGFILE keyword. TRUSTED_CONNECTION Uses a value of YES or NO, where a value of YES indicates Windows NT authentication is to be used and a value of NO indicates mixed or SQL Server authentication is to be used. USEPROCFORPREPARE Uses a value of YES or NO to indicate whether SQL Server should create temporary stored procedures for each prepared command (SQL Server 6.5 only). WSID Identifies the client workstation. Table 8-2 OLE DB Provider for ODBC Provider-Specific Keywords for SQL Server (Continued) . object. Connecting to SQL Server ADO can connect to SQL Server using either the MSDASQL OLE DB provider for ODBC or the SQLOLEDB OLE DB provider for SQL Server. The MSDASQL provider allows the. connection. Table 8-2 OLE DB Provider for ODBC Provider-Specific Keywords for SQL Server 268 Microsoft SQL Server 2005 Developer’s Guide After the OLE DB connection string is assigned to the Connection. to establish a connection with SQL Server using both the OLE DB provider for ODBC and the OLE DB provider for SQL Server. You also see how to connect to SQL Server using the ADO Connection