Accessing Data with ADO

ActiveX Data Objects (ADO) are an easy-to-use yet extensible technology for adding database access to your Web pages. You can use ADO to write compact and scalable scripts for connecting to OLE DB compliant data sources, such as databases, spreadsheets, sequential data files, or e-mail directories. OLE DB is a system-level programming interface that provides standard set of COM interfaces for exposing database management system functionality. With ADO's object model you can easily access these interfaces (using scripting languages, such as VBScript or JScript) to add database functionality to your Web applications. In addition, you can also use ADO to access Open Database Connectivity (ODBC) compliant databases.

If you are a scripter with a modest understanding of database connectivity, you will find ADO's command syntax uncomplicated and easy-to-use. If you are an experienced developer you will appreciate the scalable, high-performance access ADO provides to a variety of data sources.

For more information about ADO, visit the Data Access Technologies Web site on MSDN.

Creating a Connection String

The first step in creating a Web data application is to provide a way for ADO to locate and identify your data source. This is accomplished by means of a connection string, a series of semicolon delimited arguments that define parameters such as the data source provider and the location of the data source. ADO uses the connection string to identify the OLE DB provider and to direct the provider to the data source. The provider is a component that represents the data source and exposes information to your application in the form of rowsets.

The following table lists OLE DB connection strings for several common data sources:

To provide for backward compatibility, the OLE DB Provider for ODBC supports ODBC connection string syntax. The following table lists commonly used ODBC connection strings:

Advanced Issues to Consider When Designing Web Data Applications

For performance and reliability reasons, it is strongly recommended that you use a client-server database engine for the deployment of data driven Web applications that require high-demand access from more than approximately 10 concurrent users. Although ADO works with any OLE DB compliant data source, it has been extensively tested and is designed to work with client server databases such as SQL Server.

ASP supports shared file databases (Access or FoxPro) as valid data sources. Although some ASP example code use a shared file database, it is recommended that these types of database engines be used only for development purposes or limited deployment scenarios. Shared file databases may not be as well suited as client-server databases for very high-demand, production-quality Web applications.

If you are developing an ASP database application intended to connect to a remote SQL Server database you should also be aware of the following issues:

• Choosing Connection Scheme for SQL Server

You can choose between the TCP/IP Sockets and Named Pipes methods for accessing a remote SQL Server database. With Named Pipes, database clients must be authenticated by Windows before establishing a connection, raising the possibility that a remote computer running named pipes might deny access to a user who has the appropriate SQL Server access credentials, but does not have a Windows user account on that computer. Alternatively, connections using TCP/IP Sockets connect directly to the database server, without connecting through an intermediary computer - as is the case with Named Pipes. And because connections made with TCP/IP Sockets connect directly to the database server, users can gain access through SQL Server authentication, rather than Windows authentication.

• ODBC 80004005 Error

If the connection scheme for accessing SQL Server is not set correctly, users viewing your database application may receive an ODBC 80004005 error message. To correct this situation, try using a local named pipe connection instead of a network named pipe connection if SQL Server is running on the same computer as IIS. Windows Server 2003 family security rules will not be enforced because the pipe is a local connection rather than a network connection, which can be impersonated by the anonymous user account. Also, in the SQL Server connection string (either in the Global.asa file or in a page-level script), change the parameter SERVER=server name to SERVER=(local). The keyword (local) is a special parameter recognized by the SQL Server ODBC driver. If this solution does not work, then try to use a non-authenticated protocol between IIS and SQL Server, such as TCP/IP sockets. This protocol will work when SQL Server is running locally or on a remote computer.

• SQL Server Security

If you use SQL Server's Integrated or Mixed security features, and the SQL Server database resides on a remote server, you will not be able to use integrated Windows authentication. Specifically, you cannot forward integrated Windows authentication credentials to the remote computer. This means that you may have to use Basic authentication, which relies on the user to provide user name and password information.

For more information about these issues, see the Microsoft Product Support Services Web site.

Connecting to a Data Source

ADO provides the Connection object for establishing and managing connections between your applications and OLE DB compliant data sources or ODBC compliant databases. The Connection object features properties and methods you can use to open and close database connections, and to issue queries for updating information.

To establish a database connection, you first create an instance of the Connection object. For example, the following script instantiates the Connection object and proceeds to open a connection:

<% 
  'Create a connection object. 
  Set cnn = Server.CreateObject("ADODB.Connection") 
  'Open a connection using the OLE DB connection string. 
  cnn.Open  "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\MarketData\ProjectedSales.mdb" 
%> 

In this case, the Connection object's Open method refers to the connection string.

Executing SQL Queries with the Connection Object

With the Execute method of the Connection object you can issue commands to the data sources, such as Structured Query Language (SQL) queries. (SQL, an industry standard language for communicating with databases, defines commands for retrieving and updating information.) The Execute method can accept parameters that specify the command (or query), the number of data records affected, and the type of command being used.

The following script uses the Execute method to issue a query in the form of a SQL INSERT command, which inserts data into a specific database table. In this case, the script block inserts the name Jose Lugo into a database table named Customers.

<% 
  'Define the OLE DB connection string. 
  strConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Employees.mdb" 

  'Instantiate the Connection object and open a database connection. 
  Set cnn = Server.CreateObject("ADODB.Connection") 
  cnn.Open strConnectionString 

  'Define SQL SELECT statement.  
  strSQL = "INSERT INTO Customers (FirstName, LastName) VALUES ('Jose','Lugo')"    

  'Use the Execute method to issue a SQL query to database.  
  cnn.Execute strSQL,,adCmdText + adExecuteNoRecords 
%> 

Note that two parameters are specified in the statement used to execute the query: adCmdText and adExecuteNoRecords. The optional adCmdText parameter specifies the type of command, indicating that the provider should evaluate the query statement (in this case, a SQL query) as a textual definition of a command. The adExecuteNoRecords parameter instructs ADO to not create a set of data records if there are no results returned to the application. This parameter works only with command types defined as a text definition, such as SQL queries, or stored database procedures. Although the adCmdText and adExecuteNoRecords parameters are optional, you should specify theses parameters when using the Execute method to improve the performance of your data application.

Important Note:

ADO parameters, such as adCmdText, need to be defined before you can use them in a script. A convenient way to define parameters is to use a component type library, which is a file containing definitions for all ADO parameters. To implement a component type library, it must first be declared. Add the following the <METADATA> tag to your .asp file or Global.asa file to declare the ADO type library:

<!--METADATA NAME="Microsoft ActiveX Data Objects 2.5 Library" TYPE="TypeLib" UUID="{00000205-0000-0010-8000-00AA006D2EA4}"--> 

For details about implementing component type libraries, see the Using Constants section of the Using Variables and Constants topic.

In addition to the SQL INSERT command, you can use the SQL UPDATE and , you can use the SQL UPDATE and DELETE commands to change and remove database information.

With the SQL UPDATE command you can change the values of items in a database table. The following script uses the UPDATE command to change the Customers table's FirstName fields to Jeff for every LastName field containing the last name Smith.

<% 
  Set cnn = Server.CreateObject("ADODB.Connection") 
  cnn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Employees.mdb" 
  cnn.Execute "UPDATE Customers SET FirstName = 'Jeff' WHERE LastName = 'Smith' ",,adCmdText + adExecuteNoRecords 
%> 

To remove specific records from a database table, use the SQL DELETE command. The following script removes all rows from the Customers table where the last name is Smith:

<% 
  Set cnn = Server.CreateObject("ADODB.Connection") 
  cnn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Employees.mdb" 
  cnn.Execute "DELETE FROM Customers WHERE LastName = 'Smith'",,adCmdText + adExecuteNoRecords 
%> 

Using the Recordset Object to Manipulate Results

For retrieving data, examining results, and making changes to your database, ADO provides the Recordset object. As its name implies, the Recordset object has features that you can use, depending on your query constraints, for retrieving and displaying a set of database rows, or records. The Recordset object maintains the position of each record returned by a query, thus enabling you to step through results one item at a time.

Retrieving a Record Set

Successful Web data applications employ both the Connection object, to establish a link, and the Recordset object, to manipulate returned data. By combining the specialized functions of both objects you can develop database applications to carry out almost any data handling task. For example, the following server-side script uses the Recordset object to execute a SQL SELECT command. The SELECT command retrieves a specific set of information based on query constraints. The query also contains a SQL WHERE clause, used to narrow down a query to a specific criterion. In this example, the WHERE clause limits the query to all records containing the last name Smith from the Customers database table.

<% 
  'Establish a connection with data source.   
  strConnectionString  = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Employees.mdb"   
  Set cnn = Server.CreateObject("ADODB.Connection") 
  cnn.Open strConnectionString 

  'Instantiate a Recordset object. 
  Set rstCustomers = Server.CreateObject("ADODB.Recordset") 

  'Open a recordset using the Open method 
  'and use the connection established by the Connection object. 
  strSQL = "SELECT FirstName, LastName FROM Customers WHERE LastName = 'Smith' " 
  rstCustomers.Open  strSQL, cnn     

  'Cycle through record set and display the results 
  'and increment record position with MoveNext method. 
   Set objFirstName = rstCustomers("FirstName")  
   Set objLastName = rstCustomers("LastName")   
   Do Until rstCustomers.EOF    
     Response.Write objFirstName & " " & objLastName & "<BR>" 
     rstCustomers.MoveNext 
   Loop 

%> 

Note that in the previous example, the Connection object established the database connection, and the Recordset object used the same connection to retrieve results from the database. This method is advantageous when you need to precisely configure the way in which the link with the database is established. For example, if you needed to specify the time delay before a connection attempt aborts, you would need to use the Connection object to set this property. However, if you just wanted to establish a connection using ADO's default connection properties, you could use Recordset object's Open method to establish a link:

<% 
  strConnectionString  = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Employees.mdb" 
  strSQL = "SELECT FirstName, LastName FROM Customers WHERE LastName = 'Smith' " 
  Set rstCustomers = Server.CreateObject("ADODB.Recordset") 

  'Open a connection using the Open method 
  'and use the connection established by the Connection object. 
  rstCustomers.Open  strSQL, strConnectionString     

  'Cycle through the record set, display the results, 
  'and increment record position with MoveNext method. 
   Set objFirstName = rstCustomers("FirstName")  
   Set objLastName = rstCustomers("LastName")  
   Do Until rstCustomers.EOF 
      Response.Write objFirstName & " " & objLastName & "<BR>" 
      rstCustomers.MoveNext 
   Loop 
%> 

When you establish a connection using the Recordset object's Open method to establish a connection, you are implicitly using the Connection object to secure the link. For more information, see Microsoft ActiveX Data Objects (ADO) Help available from the Microsoft Universal Data Access Web site.

It is often useful to count the number of records returned in a recordset. The Open method of the Recordset object enables you to specify an optional cursor parameter that determines how the underlying provider retrieves and navigates the recordset. By adding the adOpenKeyset cursor parameter to the statement used to execute the query, you enable the client application to fully navigate the recordset. As a result, the application can use the RecordCount property to accurately count the number of records in the recordset. See the following example:

<% 
    Set rs = Server.CreateObject("ADODB.Recordset") 
    rs.Open "SELECT * FROM NewOrders", "Provider=Microsoft.Jet.OLEDB.3.51;Data Source='C:\CustomerOrders\Orders.mdb'", adOpenKeyset, adLockOptimistic, adCmdText  

    'Use the RecordCount property of the Recordset object to get count. 
    If rs.RecordCount >= 5 then 
      Response.Write "We've received the following " & rs.RecordCount & " new orders<BR>"  

      Do Until rs.EOF 
        Response.Write rs("CustomerFirstName") & " " & rs("CustomerLastName") & "<BR>" 
        Response.Write rs("AccountNumber") & "<BR>" 
        Response.Write rs("Quantity") & "<BR>"          
        Response.Write rs("DeliveryDate") & "<BR><BR>" 
            rs.MoveNext 
      Loop 

    Else              
      Response.Write "There are less than " & rs.RecordCount & " new orders."        
    End If 

   rs.Close 
%> 

Improving Queries with the Command Object

With the ADO Command object you can execute queries in the same way as queries executed with the Connection and object you can execute queries in the same way as queries executed with the Connection and Recordset object, except that with the Command object you can prepare, or compile, your query on the database source and then repeatedly reissue the query with a different set of values. The benefit of compiling queries in this manner is that you can vastly reduce the time required to reissue modifications to an existing query. In addition, you can leave your SQL queries partially undefined, with the option of altering portions of your queries just prior to execution.

The Command object's Parameters collection saves you the trouble of reconstructing your query each time you want to reissue your query. For example, if you need to regularly update supply and cost information in your Web-based inventory system, you can predefine your query in the following way:

<%   
    'Open a connection using Connection object. Notice that the Command object 
    'does not have an Open method for establishing a connection. 
    strConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Inventory.mdb"  
    Set cnn = Server.CreateObject("ADODB.Connection") 
    cnn.Open strConnectionString 

    'Instantiate Command object; use ActiveConnection property to attach  
    'connection to Command object. 
    Set cmn= Server.CreateObject("ADODB.Command") 
    Set cmn.ActiveConnection = cnn 

    'Define SQL query. 
    cmn.CommandText = "INSERT INTO Inventory (Material, Quantity) VALUES (?, ?)"  

    'Save a prepared (or pre-compiled) version of the query specified in CommandText 
    'property before a Command object's first execution.  
    cmn.Prepared = True 

    'Define query parameter configuration information. 
    cmn.Parameters.Append cmn.CreateParameter("material_type",adVarChar, ,255 ) 
    cmn.Parameters.Append cmn.CreateParameter("quantity",adVarChar, ,255 ) 

    'Define and execute first insert. 
    cmn("material_type") = "light bulbs"  
    cmn("quantity") = "40"  
    cmn.Execute ,,adCmdText + adExecuteNoRecords 

    'Define and execute second insert. 
    cmn("material_type") = "fuses"  
    cmn("quantity") = "600"  
    cmn.Execute ,,adCmdText + adExecuteNoRecords 
    . 
    . 
    . 
  %> 

Important Note:

ADO parameters, such as adCmdText, are simply variables, this means that before using an ADO parameter in a data access script you need to define its value. Since ADO uses a large number of parameters, it is easier to define parameters by means of a component type library, a file containing definitions for every ADO parameter and constant. For details about implementing ADO's type library, see the Using Constants section of the Using Variables and Constants topic.

In the previous example, you will note that the script repeatedly constructs and reissues a SQL query with different values, without having to redefine and resend the query to the database source. Compiling your queries with the Command object also offers you the advantage of avoiding problems that can arise from concatenating strings and variables to form SQL queries. In particular, by using the Command object's Parameter collection, you can avoid problems related to defining certain types of string, date, and time variables. For example, SQL query values containing apostrophes (') can cause a query to fail:

strSQL = "INSERT INTO Customers (FirstName, LastName) VALUES ('Robert','O'Hara')"  

Note that the last name O'Hara contains an apostrophe, which conflicts with the apostrophes used to denote data in the SQL VALUES keyword. By binding the query value as a Command object parameter, you avoid this type of problem.

Combining HTML Forms and Database Access

Web pages containing HTML forms can enable users to remotely query a database and retrieve specific information. With ADO you can create surprisingly simple scripts that collect user form information, create a custom database query, and return information to the user. Using the ASP Request object, you can retrieve information entered into an HTML form and incorporate this information into your SQL statements. For example, the following script block inserts information supplied by an HTML form into a table. The script collects the user information with the Request object 's Form collection.

<% 
  'Open a connection using Connection object. The Command object 
  'does not have an Open method for establishing a connection. 
   strConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=D:\CompanyCatalog\Seeds.mdb"  
    Set cnn = Server.CreateObject("ADODB.Connection") 
    cnn.Open strConnectionString 

  'Instantiate Command object 
  'and  use ActiveConnection property to attach 
  'connection to Command object. 
  Set cmn= Server.CreateObject("ADODB.Command") 
  Set cmn.ActiveConnection = cnn 

  'Define SQL query. 
  cmn.CommandText = "INSERT INTO MySeedsTable (Type) VALUES (?)"  

  'Define query parameter configuration information. 
  cmn.Parameters.Append cmn.CreateParameter("type",adVarChar, ,255) 

  'Assign input value and execute update. 
  cmn("type") = Request.Form("SeedType")  
  cmn.Execute ,,adCmdText + adExecuteNoRecords 
%> 

For more information about forms and using the ASP Request object, see Processing User Input.

Managing Database Connections

One of the main challenges of designing a sophisticated Web database application, such as an online order entry application that services thousands of customers, is properly managing database connections. Opening and maintaining database connections, even when no information is being transmitted, can severely strain a database server's resources and result in connectivity problems. Well designed Web database applications recycle database connections and compensate for delays due to network traffic.

Timing Out a Connection

A database server experiencing a sudden increase in activity can become backlogged, greatly increasing the time required to establish a database connection. As a result, excessive connection delays can reduce the performance of your database application.

With the Connection object's ConnectionTimeout you can limit the amount of time that your application waits before abandoning a connection attempt and issuing an error message. For example, the following script sets the ConnectionTimeout property to wait twenty seconds before cancelling the connection attempt:

Set cnn = Server.CreateObject("ADODB.Connection") 
cnn.ConnectionTimeout = 20 
cnn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Inventory.mdb" 

The default for the ConnectionTimeout property is 30 seconds.

Pooling Connections

Connection pooling enables your Web application to use a connection from a pool, or reservoir of free connections that do not need to be reestablished. After a connection has been created and placed in a pool, your application reuses that connection without having to perform the connection process. This can result in significant performance gains, especially if your application connects over a network or repeatedly connects and disconnects. In addition, a pooled connection can be used repeatedly by multiple applications.

OLE DB Session Pooling

OLE DB has a pooling feature, called session pooling, optimized for improving connectivity performance in large Web database applications. Session pooling preserves connection security and other properties. A pooled connection is only reused if matching requests are made from both sides of the connection. By default, the OLE DB providers for Microsoft SQL server support session pooling. This means that you do not have to configure your application, server, or database to use session pooling. However, if your provider does not support session pooling by default, you need to create a registry setting to enable session pooling. For more information about session pooling, see the OLE DB 2.0 Software Development Kit (SDK).

ODBC Connection Pooling

If you want your ODBC driver to participate in connection pooling you must configure your specific database driver and then set the driver's CPTimeout property in the Windows registry. The CPTimeout property determines the length of time that a connection remains in the connection pool. If the connection remains in the pool longer than the duration set by CPTimeout, the connection is closed and removed from the pool. The default value for CPTimeout is 60 seconds.

You can selectively set the CPTimeout property to enable connection pooling for a specific ODBC database driver by creating a registry key with the following settings:

\HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\driver-name\CPTimeout = timeout  
 (REG_SZ, units are in seconds) 

For example, the following key sets the connection pool timeout to 180 seconds (3 minutes) for the SQL Server driver.

\HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\SQL Server\CPTimeout = 180 

Using Connections Across Multiple Pages

Although you can reuse a connection across multiple pages by storing the connection in ASP's Application object, doing so may unnecessarily keep open a connection open, defeating the advantages of using connection pooling. If you have many users that need to connect to the same ASP database application, a better approach is to reuse a database connection string across several Web pages by placing the string in ASP's Application object. For example, you can specify a connection string in the Global.asa file's Application_OnStart event procedure, as in the following script:

Application("ConnectionString") = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Inventory.mdb" 

Then in each ASP file that accesses the database, you can write

<OBJECT RUNAT=SERVER ID=cnn PROGID="ADODB.Connection"></OBJECT> 

to create an instance of the connection object for the page, and use the script

cnn.Open Application("ConnectionString") 

to open the connection. At the end of the page, you close the connection with

cnn.Close 

In the case of an individual user who needs to reuse a connection across multiple Web pages, you may find it more advantageous to use the Session object rather than the Application object for storing the connection string.

Closing Connections

To make the best use of connection pooling, explicitly close database connections as soon as possible. By default, a connection terminates after your script finishes execution. However, by explicitly closing a connection in your script after it is no longer needed, you reduce demand on the database server and make the connection available to other users.

You can use Connection object's Close method to explicitly terminate a connection between the Connection object and the database. The following script opens and closes a connection:

<% 
  strConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Inventory.mdb" 
  Set cnn = Server.CreateObject("ADODB.Connection") 
  cnn.Open strConnectionString 
  cnn.Close 
%>