Microsoft SQL Server 2005 Developer’s Guide- P32 ppsx

Chapter 8: Developing Database Applications with ADO 289 After the DisplayForwardGrid subroutine completes, then all the data contained in the rs Recordset object is displayed in the grid. The end user can view the data and scroll through it using the navigation tools provided by the grid object. Once the Recordset object has been processed, control is returned to the calling routine. Then the Recordset object is closed and its resources are released by setting it to Nothing. Closing a Recordset Before ending your application, close any open Recordset objects using the Recordset object’s Close method. An example of the Close method follows: rs.Close You could also close the connection by setting the Recordset object to nothing, as follows: Set rs = Nothing Figure 8-11 Using a ForwardOnly Recordset 290 Microsoft SQL Server 2005 Developer’s Guide TIP A good programming practice is to always close any open Recordset objects immediately as soon as they’re no longer needed by your application. Using a Keyset Recordset Object The preceding code example illustrated how to use ADO to create a simple Recordset object that uses a forward-only cursor. The forward-only cursor is fast and efficient, but it’s not as capable as the other cursor types. For instance, while the forward-only cursor can only make a single pass through a Recordset in forward order, a keyset cursor allows multiple passes, as well as forward and backward scrolling. Processing a Keyset Recordset in Forward Order The following code illustrates how to use an ADO Recordset object that uses a keyset cursor: Private Sub KeysetRecordset(cn As ADODB.Connection) Dim rs As New ADODB.Recordset ' Associate the Recordset with the open connection rs.ActiveConnection = cn rs.Source = "Select * From Sales.SalesTerritory Order By TerritoryID" ' Pass the Open method the SQL and Recordset type parameters rs.Open , , adOpenKeyset, adLockReadOnly ' Display the recordset use a 1 to display in forward order DisplayKeysetGrid rs, hflxResults, 1 rs.Close Set rs = Nothing End Sub In this example, a new ADO Recordset object named rs is created. Then the ActiveConnection property of the rs Recordset object is set to cn, which is the name of an existing ADO Connection object that has an active database connection. Next, the Recordset object’s Source property is assigned a simple SQL Select statement that returns all the rows and columns from the Sales.SalesTerritory table, ordered according to the values of the TerritoryID column. Chapter 8: Developing Database Applications with ADO 291 NOTE For publication purposes, several of the examples in this chapter use simple, unqualified SQL Select statements. Unless you know the target tables are relatively small, however, you should try to keep your own result sets as small as possible by explicitly defining just the desired columns and using the SELECT statement’s WHERE clause to retrieve only the rows your application will use. Next, the Open method executes the source SQL statement on the target database. In this example, the first two parameters of the Open method needn’t be specified, because they were already set using the Source and ActiveConnection properties of the Recordset object. The value of adOpenKeyset in the third parameter indicates this Recordset object will use a keyset cursor. The value of adLockReadOnly in the fourth parameter makes the Recordset read-only. After the Open method has executed the query, the DisplayKeysetGrid subroutine displays the contents of the rs Recordset object in a grid. The DisplayKeysetGrid subroutine use three parameters: the name of an ADO Recordset object, the name of an MSHFlexGrid object, and an integer value that controls the direction in which the data will be displayed. Because the capabilities of the keyset cursor are greater than those of the forward-only cursor, this subroutine contains a couple of enhancements that can take advantage of those capabilities. The code for the DisplayKeysetGrid subroutine is shown here: Private Sub DisplayKeysetGrid _ (rs As ADODB.Recordset, hflxResults As MSHFlexGrid, _ Optional nDirection As Integer) Dim fld As ADODB.Field Dim nForward As Integer Dim nReverse As Integer On Error Resume Next nForward = 1 nReverse = 2 'If the direction parameter is not provided use forward If IsMissing(nDirection) Then nDirection = nForward End If ' Setup the hflxResults hflxResults.Redraw = False hflxResults.Clear hflxResults.FixedCols = 0 hflxResults.FixedRows = 0 292 Microsoft SQL Server 2005 Developer’s Guide hflxResults.Cols = rs.Fields.Count rs.MoveLast hflxResults.Rows = rs.RecordCount + 1 hflxResults.Row = 0 hflxResults.Col = 0 'Setup the hflxResults headings For Each fld In rs.Fields hflxResults.Text = fld.Name hflxResults.ColAlignment(hflxResults.Col) = 1 hflxResults.ColWidth(hflxResults.Col) = _ Me.TextWidth(fld.Name & "AA") If hflxResults.Col < rs.Fields.Count - 1 Then hflxResults.Col = hflxResults.Col + 1 End If Next fld If nDirection = nForward Then ' Position at beginning rs.MoveFirst Else ' Position at end rs.MoveLast End If ' Check for either the beginning or the end of the recordset Do Until rs.BOF Or rs.EOF ' Set the position in the hflxResults hflxResults.Row = hflxResults.Row + 1 hflxResults.Col = 0 'Loop through all fields For Each fld In rs.Fields hflxResults.Text = fld.Value If hflxResults.ColWidth(hflxResults.Col) < _ Me.TextWidth(fld.Value & "AA") Then hflxResults.ColWidth(hflxResults.Col) = _ Me.TextWidth(fld.Value & "AA") End If If hflxResults.Col < rs.Fields.Count - 1 Then hflxResults.Col = hflxResults.Col + 1 End If Next fld Chapter 8: Developing Database Applications with ADO 293 ' Read according to direction If nDirection = nForward Then rs.MoveNext Else rs.MovePrevious End If Loop ' If there was no data returned set the grid to show 2 rows If hflxResults.Rows < 2 Then hflxResults.Rows = 2 End If ' Set the fixed rows and redraw the grid hflxResults.FixedRows = 1 hflxResults.Redraw = True End Sub As in the DisplayForwardGrid subroutine presented earlier, the parameters used by the DisplayKeysetGrid subroutine allow it to be reused by many different Recordset and Grid objects. However, because this subroutine is intended to be used with keyset cursors, which support both forward and backward scrolling, it uses an additional optional parameter that can control the direction the data is to be listed. The internals of this subroutine are also a bit different than the DisplayForwardGrid subroutine to allow it to take advantage of some of the additional capabilities provided the Keyset Recordset object. At the beginning of this subroutine, an ADO Field object is declared, followed by two Integer variables. The ADO Field object is used to contain and manipulate the values of each column returned by the Recordset object. The Integer variables are used to determine the direction the data will be presented and to improve the readability of the code. Next, the optional parameter is tested to determine if it was supplied. If the parameter is missing, then the default Recordset processing direction is set to forward. The section of code immediately following these variables sets up the grid. This section is similar to the DisplayForwardGrid shown earlier, but one notable difference exists. Because keyset cursors support backward movement, this subroutine is able to use the Recordset object’s MoveLast method to move to the end of the Recordset. This populates the Recordset object, which can then be used to size the grid to the appropriate number of rows. This technique results in a slightly better performance because the grid needs to be sized only once rather than resized as each 294 Microsoft SQL Server 2005 Developer’s Guide row is read. In this example, the grid is sized using the value from the Recordset’s RecordCount property, plus one additional row for the column headings. Next, the grid columns are sized and the column headings are set to the database column names for each Field object in the Recordset object’s Fields collection. While this code is identical to the ForwardOnlyGrid subroutine, the next section of code after that illustrates how the keyset cursor’s capability to scroll forward and backward is used. The value passed in to the third parameter of the DisplayKeysetGrid subroutine controls the direction the Recordset data is to be listed in the grid. A value of 1 lists the data in forward order, while a value of 2 causes the Recordset data to be listed in backward order. The If test compares the value of the nDirection variable to the value of the Integer variable named nForward. If the value is equal, then the Recordset is displayed in forward order and the cursor is positioned to the beginning of the Recordset object using the MoveFirst method. Otherwise, the contents of the Recordset are displayed in reverse order and the cursor is positioned to the last row in the Recordset using the rs Recordset object’s MoveLast method. The next section of code reads the contents of the Recordset object and is essentially the same as the code in the previous DisplayForwardGrid subroutine. A Do loop is used to read all the rows in the Recordset object. And for every row, a For Each loop copies each row’s data from the Fields collection to the grid. Two notable differences exist, however. First, because the Recordset object may be processed either from front-to-back or back-to-front, the Do Until loop has been modified to check for either the BOF indicator or the EOF indicator. As you would expect, the EOF property contains a value of True when the last row in the Recordset has been read using the MoveNext method, while the BOF property contains a value of True when the first row in the Recordset object is read using the MovePrevious method. Second, after the For Each loop has been executed and all the Field values for the current row have been copied to the grid, the nDirection variable is checked again to determine which row is to be read next. If the nDirection variable indicates the Recordset object is being processed in a forward direction, then the MoveNext method is executed to read the next row. Otherwise, the rs Recordset object’s MovePrevious method is executed to read the prior row. After the DisplayKeysetGrid subroutine has completed, the contents of the Recordset object are displayed in the grid, allowing the end user to view the data. Then, the control is returned to the calling KeysetRecordset subroutine, where the Recordset object is closed and its resources are released by setting the Recordset object to Nothing. Processing a Keyset Recordset in Reverse Order While the DisplayKeysetGrid subroutine has the capability of displaying the data in a Recordset object in either Chapter 8: Developing Database Applications with ADO 295 forward or backward order, the preceding example only displayed the data in a forward fashion. The following subroutine illustrates how the DisplayKeysetGrid subroutine can be used with a Keyset type of Recordset to display the Recordset data in reverse order: Private Sub KeysetRecordsetReverse(cn As ADODB.Connection) Dim rs As New ADODB.Recordset ' Pass the Open method the SQL and Recordset type parameters rs.Open "Select * From Sales.SalesTerritory", _ cn, adOpenKeyset, adLockReadOnly, adCmdText ' Display the grid use a 2 to display in reverse order DisplayKeysetGrid rs, Grid, 2 rs.Close Set rs = Nothing End Sub The example demonstrates a couple of significant differences from the previous examples. In addition to using the DisplayKeysetGrid subroutine to display the Recordset in reserve order, this subroutine also shows how to use the first and second parameters of the Recordset object’s Open method to pass in the source and connection information. Using the first and second parameters of the Open method is an alternative to assigning values explicitly to the Recordset object’s ActiveConnection and Source properties. The first parameter sets the Source property to the simple SQL Select statement that can retrieve all the rows from the Sales.SalesTerritory table. The second parameter sets the ActiveConnection to an existing Connection object named cn. The third parameter specifies a keyset cursor. The fourth parameter sets the lock type to read-only, and the fifth parameter identifies the first (“source”) parameter as command text. After the Open method completes, the DisplayKeysetGrid function is called. The name of the open Recordset object is passed into the first parameter, the name of an existing grid is used in the second parameter, and the value of 2 is used in the third parameter to set the display order to backward. You can see the Keyset Recordset object displayed in reserve order in Figure 8-12. Using Data Bound Recordsets The previous examples illustrated how to process the contents of a Recordset object manually and display them on a Hierarchical FlexGrid. Manually processing the Recordset object gives you complete control over how you want the data to be 296 Microsoft SQL Server 2005 Developer’s Guide presented, as well as how you want the grid to be displayed. For instance, the earlier examples illustrated presenting the column names at the top of the grid, dynamically resizing the grid columns according to the size of the data, and presenting the data in a different order than it was retrieved. Sometimes, however, these types of capabilities are more than is required and you might simply want to display a result set in a grid quickly. Using the Hierarchical FlexGrid’s data-bound capabilities in conjunction with the ADO Recordset object lets you quickly display the contents of an ADO Recordset with little coding. NOTE Data binding refers to creating an association between a database object like an ADO Recordset object and a grid. When an interface object is bound to an ADO object, changing the data that’s displayed in the interface object automatically changes the data in the underlying database object. Data binding is also often used between an ADO Recordset object and a group of Text Boxes to create simple data entry forms. Figure 8-12 Display a Keyset Recordset in reverse order Chapter 8: Developing Database Applications with ADO 297 The listing that follows illustrates how to bind the Hierarchical FlexGrid to an ADO Recordset object: Private Sub DataBoundGrid(cn As ADODB.Connection) Dim rs As New ADODB.Recordset ' Open the recordset With rs ' Set the properties & open .Source = "Select * From Sales.SpecialOffer" .ActiveConnection = cn .CursorType = adOpenKeyset .LockType = adLockOptimistic .Open End With ' Populate the grid Set hflxResults.DataSource = rs End Sub As in the previous examples, in this example you can see a new instance of the Recordset object created at the top of the subroutine. And in this example, the Recordset object’s important connection attributes are set inside a With block. The Source property is assigned a SQL statement that will retrieve all the rows and columns from the Sales.SpecialOffer table. The ActiveConnection property is assigned an instance of the cn ADO Connection object that’s passed into the subroutine as a parameter. Next, the CursorType and LockType properties are set to adOpenKeyset and adLockOptimistic. The rs Recordset object’s Open method is then executed to run the query and return the data to the Recordset object. After the Recordset has been opened, it can then be assigned to the Hierarchical Flexgrids’s DataSource property using the Set statement. As soon as the DataSource property is set to an open Recordset object, the grid is automatically populated with the contents of the Recordset. Figure 8-13 presents the sample results of using a data-bound grid. Assigning the DataSource property of a Hierarchical FlexGrid is an extremely easy method for displaying the contents of the Recordset, but it lacks the control that’s available when you manually assign the Recordset values to the grid. For instance, there’s no way to control what’s displayed in the grid column headings. There’s also no way to size the grid columns, align the data in the cells, or control the formatting of the data displayed. 298 Microsoft SQL Server 2005 Developer’s Guide Finding and Bookmarking Rows ADO Recordset objects support several methods for navigating through the contents of the Recordset. Previous examples have illustrated using the MoveFirst, MoveLast, MoveNext, and MovePrevious methods. All these methods are intended for sequential processing, where you read one record after another in the order in which they occur in the Recordset. However, ADO Keyset and Dynamic Recordsets objects also support several methods that provide random navigation through a Recordset. In the following example, you see how the Find method can be used to locate a given row, or group of rows, within a Recordset, as well as how a bookmark can be used to jump quickly to a specific row. An ADO Bookmark is a property of the Recordset object that returns a unique identifier for the current record. This unique record identifier doesn’t change during the life of a Recordset. By setting this property to a valid bookmark, you can also use this property to move the pointer to a specified record. The following listing illustrates how to use the Find method and how to save an ADO Recordset bookmark: Figure 8-13 Using a data-bound grid . nothing, as follows: Set rs = Nothing Figure 8-11 Using a ForwardOnly Recordset 290 Microsoft SQL Server 2005 Developer’s Guide TIP A good programming practice is to always close any open Recordset. False hflxResults.Clear hflxResults.FixedCols = 0 hflxResults.FixedRows = 0 292 Microsoft SQL Server 2005 Developer’s Guide hflxResults.Cols = rs.Fields.Count rs.MoveLast hflxResults.Rows. performance because the grid needs to be sized only once rather than resized as each 294 Microsoft SQL Server 2005 Developer’s Guide row is read. In this example, the grid is sized using the value from