Any time you interact with a database, you’ll need to use a special application programming interface (API) that allows you to communicate with the database. For most purposes, you can use one of the versions of ActiveX Data Objects, commonly referred to as ADO.

Prior to using ADO in your project however, you need to add a reference to it in the VBE. To do this, select Tools/References from the Visual Basic Editor menu and check the checkbox next to the latest version of ADO on your computer as illustrated in Figure 1.

Figure 1 - Adding a reference to Microsoft ActiveX Data Objects
Click to enlarge

Listing 1 shows how to connect to the Northwind sample database, execute a query, and copy the results on to a worksheet. Enter the following listing in the code module associated with Sheet1 (you could also insert a new module and enter it there).

Listing 1: This listing demonstrates basic data retrieval from an Access database.

'NOTE: Set a reference in the VBE to the latest version of
' the Microsoft ActiveX Data Objects Library on your computer.

' resume at the ExitPoint label to clean up object variables
Resume ExitPoint
End Sub

Running listing 1 produces the results shown in Figure 2.

Figure 2: Success! - Click to enlarge

Querying a database programmatically using ADO generally involves four tasks. First, you need to define a connection string. A connection string is simply the details required by ADO to locate and connect to the desired database. While I’ve just defined a connection string in this example, it is also common to use the ADO Connection object to handle the details associated with connecting to a database.

Second, you need to build the SQL statement that will return the data that you’re interested in. ADO has a Command object that you can use to do this — or you could just define a SQL statement and store it in a string as I have in the example.

Third, you need to use the ADO Recordset object to execute the query (or command) against the connection and store the results.

Finally, once you have the results in a Recordset, you need to display them somehow. Using the CopyFromRecordset method associated with a Range object is the easiest way to go about this. In a future column I’ll demonstrate a technique that is a little more flexible.

The Selection object represents the current selection in a window or pane. It is useful when you are writing macros that interact with the user.

When programming in Word, you frequently need to know things such as which page the user is working on, the number of pages in the document, the line number of the insertion point, the column number of the insertion point, and on and on.

Surprisingly, you only need to know one property to determine the answer to these questions and many more:

Selection.Information(wdInformation)

where wdInformation represents the information you want returned.

The Information property is unique, unlike other properties I have discussed in this column. The Information property is a parameterized property. Generally properties do not use parameters. The Information property, however, accepts a wdInformation enumeration consisting of 35 options, shown in Figure 1.

Figure 1: Browsing Members of the wdInformation enumeration

As shown in Listing 1, using the Information property is very easy.

Listing 1: A simple demonstration of the Selection.Information property

Sub SelectionInformation()
Debug.Print "Selection starts at column: " & _
Selection.Information(wdFirstCharacterColumnNumber)

Debug.Print "The selection starts on page " & _
Selection.Information(wdActiveEndPageNumber) _
& ". There are " & _
Selection.Information(wdNumberOfPagesInDocument) & _
" page(s) in the document."
End Sub

To test this listing, enter the text =Rand(12,12) and press Enter to easily add a bunch to test data into a document. Then, experiment with the listing by placing the cursor at different locations in the document and running the macro. A sample of the output is shown below.

Listing 2: Example output from the SelectionInformation procedure

Selection starts at column: 11
Selection starts at line: 8
The selection starts on page 2. There are 5 page(s) in the document.

For details regarding the types of operations you can perform with Selection.Information and the correct enumeration value for each operation, visit

http://msdn2.microsoft.com/en-us/library/bb213848.aspx

A much simpler approach is to use custom number formats. For example, it is possible to display a number scaled by thousands using this number format:

#,##0,

Using custom number formats does not change the underlying value, and the formats are trivial to modify.

To take this a step further, it is relatively simple to add a scaling feature using a combination of named ranges, a simple drop-down list using the data validation feature, and a pinch of VBA. As an example, consider the worksheet shown in Figure 1. (NOTE: Although these images show Excel 2007, the same results can be achieved using Excel 2003.)

Figure 1: Step 1 - Name the range of numbers that should be scaled.

The first step is to create a named range consisting of all the cells that should be scaled. In Figure 1, I’ve named the range Scale_Range.

Figure 2: Step 2 - Create a named range for the cell that specifies the scaling factor.

The next step is to create a named range for the cell that contains the scaling factor options. In Figure 2, I’ve named this Scale_Factor. Additionally, I’ve added data validation to this cell to provide the list of options and the drop-down functionality.

The final step is to add the code shown in Listing 1 to the Sheet1 object in the Visual Basic Editor.

Listing 1: A method for providing scaling capabilities

Private Sub Worksheet_Change(ByVal Target As Range)
If Target = Me.Range("Scale_Factor") Then
ScaleNumbers
End If
End Sub

Private Sub ScaleNumbers()
Select Case Me.Range("Scale_Factor").Value
Case Is = "(in $)"
Me.Range("Scale_Range").NumberFormat = "#,##0"
Case Is = "(in thousands of $)"
Me.Range("Scale_Range").NumberFormat = "#,##0,"
Case Is = "(in millions of $)"
Me.Range("Scale_Range").NumberFormat = "#,##0,,"
Case Else
Me.Range("Scale_Range").NumberFormat = "#,##0"
End Select
End Sub

The Worksheet_Change procedure is an event handler that Excel calls automatically anytime something changes on Sheet1. The Target parameter represents the range object (i.e., cell) that changed. If the cell that changed is the cell containing the scaling choices, the ScaleNumbers procedure is called.

The ScaleNumbers procedure examines the value of the Scale_Factor named range and — depending on the desired scaling — uses the NumberFormat property to set a custom number format.

As you can see in Figure 3, the number appears scaled on the worksheet but the underlying value of the cell is unchanged.

Figure 3

The key to this technique is using the Err object to gather information about the type of error that occurred and then take an appropriate action. Nearly every type of error that can occur at runtime is assigned a number and description and this information is surfaced through the Err object. The Err object is an object that is automatically created by VBA whenever an error occurs.

As an example, consider Listing 1 below.

Listing 1: Flexible Error Handling

Sub FixErrorStrategy()
Dim x As Integer
Dim z As Integer

ErrHandler:
If Err.Number = 11 Then
MsgBox "Division by zero error. " & _
"Changing denominator to 1."
z = 1
' Resume execution with the statement that
' caused the error.
Resume
Else
MsgBox "Unrecoverable Error: " & _
Err.Number & " - " & Err.Description
End If
End Sub

Listing 1 loops through the numbers 1 through 10 and divides each number by the number stored in variable z (which is mistakenly set to 0 initially). When an error occurs, execution proceeds to the block of code after the ErrHandler label. This code examines the Err.Number and takes action if the error is error number 11 -– the error number associated with division by zero. For all other errors, the procedure will display information about the error and then exit the procedure.

The ErrHandler code block uses the Resume statement after fixing the condition that caused the error to resume execution at the statement that initially caused the error. When the division by zero error occurs, the procedure sets the value of z to 1, then the Resume statement causes execution to resume at the Debug.Print x/z statement. From that point on, the procedure runs as expected and produces the following output in the Immediate window.

1
2
3
4
5
6
7
8
9
10

This error handling pattern is very typical of VBA procedures that require anything more than the most elementary error handling. Stay tuned next week for a great tip on scaling Excel worksheet numbers programmatically.

Figure 1: The default runtime error experience

Before moving into basic error handling strategies, I’ll demonstrate the default strategy — no error handling. If there is no error handling present, VBA will display a runtime error when an error occurs and present the option to either End the macro or Debug it. Listing 1 shows an example listing that will generate a division by zero error.

Listing 1: A procedure that does not use error handling.

Sub NoErrorHandlingStratgy()
Dim x As Integer

' This line will only be reached if no errors occur.
MsgBox "Finished - without errors"
End Sub

Running Listing 1 produces the dialog box shown in Figure 1.

The error-handling strategy is simply to ignore any errors and continue executing code. As an example, consider Listing 2. This listing attempts to do the same thing as Listing 1 except it includes the statement On Error Resume Next near the beginning of the procedure.

Listing 2: A procedure that ignores all errors

Sub IgnoreEverythingStratgy()
Dim x As Integer

' This line will be reached no matter what.
MsgBox "Finished - with or without errors"
End Sub

This strategy is helpful when you have procedures in which the individual statements don’t rely on previous statements. In other words, if one line doesn’t execute due to an error, there are no adverse affects to the remaining statements.

If there a procedure is performing more critical operations and there is a dependency between the various statements in a procedure, it might be better to gracefully quit or exit the procedure the first time that an error occurs. At first, this might sound exactly like what you get by not using any error handling. However, there are critical differences.

First, you get to control the user experience rather than the VBA execution engine. For example, you might not want to give the user the ability to debug your code. Or you might choose to not even notify the user that an error occurred. Finally, if you have other procedures that need to run after the procedure that caused the error, these other procedures can still run. Without error handling, all execution stops and any following procedures will not be run.

To use this strategy, use the On Error GoTo ErrHandler statement. ErrHandler is actually a line label - you can use a different label if you prefer. Listing 3 shows an example of this strategy.

Listing 3: A procedure that uses an error handler

Sub QuitOnFirstErrorStrategy()
Dim x As Integer

' The following code only runs if an
' error occurs.
ErrHandler:
MsgBox "Did not finish - error: " & _
Err.Description
End Sub

These two basic strategies can significantly improve your ability to write more user friendly and robust code. Next week I’ll demonstrate additional error handling strategies that provide even more flexibility to selectively handle some errors but not others.

While Excel provides Find and FindNext methods to search cells, using them correctly isn’t as easy as one might think. The reason that using Find is more difficult than it should be is that as long as it finds at least one match, calls to FindNext will never terminate because it will repeatedly find the same item. This happens because once Excel gets to the last cell in the range it wraps around and resumes searching with the first cell in the range.

The key to using Find and FindNext is saving the address of the first cell that is found and then comparing the address of subsequent finds with the saved address. When a subsequent address equals the saved address, the entire range has been searched.

Listing 1 provides and example illustrating this method. It looks a lot longer than it really is because of all the comments I’ve added.

Listing 1: Using Find and FindNext to search cells on a worksheet

Sub FindExample()
Dim rgFound As Range
Dim sFirstFoundAddress As String

MsgBox “The active sheet has been searched.”, _
vbOKOnly, “Search Complete”
End Sub

One thought that I’d like to share relates to the use of ActiveSheet. Generally, ActiveSheet will resolve to a worksheet object. However, when using ActiveSheet, be sure to make sure that the active sheet is actually a worksheet. It could be a chart sheet for example which may result in runtime errors if you have assumed that ActiveSheet is a worksheet. It is easy to validate that ActiveSheet is a worksheet by examining the Type property as I’ve done near the beginning of Listing 1.

To test this procedure, simply populate several cells in a worksheet with the value “NAR”. With the worksheet active, run the FindExample macro.

One of our staff asked me if there was a way in Excel to take this information:

NAR123456

and replace it with this

123-456

In other words, the person wants to delete the “NAR” and place a hyphen after the first three numbers. Evidently, she has to do this frequently on large spreadsheets. This has got to be an easy thing to do, but I don’t have the skill set needed to come up with the solution. Can you help? Thanks.

Using the string manipulation functions that I covered in the previous two columns, it is possible to make quick work of this problem. However, depending on the layout of the spreadsheet in question, it may be even easier to handle to problem using formulas. An example of this is shown in Figure 1.

Figure 1: Using formulas to manipulate text

The difference between the “Variable” and the “Fixed” columns is that the formula in the variable column assumes that the number of digits after the “NAR” part is variable. The formula for the fixed column assumes that there are exactly 6 digits after the “NAR” part.

If the text can appear anywhere on the worksheet, using formulas isn’t an option because you don’t know ahead of time where the text will show up and it isn’t practical to re-create the formula everywhere it is needed.

The solution in VBA is twofold. First, build a procedure that will convert the text as desired. Second, provide a way to search all of the cells on the worksheet. I’ll only be covering the first issue this week.

Listing 1 shows a simple implementation of one of several approaches to this problem. This implementation is rather simple because it relies on the end user to perform the “searching” for cells that need to be fixed. Then, by assigning a shortcut key to the FixCell macro such as Ctrl + F, one can select individual cells that need to be fixed and press Ctrl + F to fix the cell. FixCell determines if the value in the cell is actually a value that needs to be fixed and, if so, calls the ConvertString function to perform the conversion. Finally, FixCell updates the active cell with the value returned from ConvertString.

Listing 1: A VBA function to convert the string.

' Very simplistic procedure to
' try and fix a cell
' Assigned to shortcut key: ctrl+f

' Return the result
ConvertString = sResult
End Function

Providing a way to search a worksheet for all possible cells that need to be fixed requires an entire column which I will save for another week.

Text in VBA is usually stored in string variables. When discussing text manipulation, then, it is common to refer to text as a string. Perhaps the most common need when it comes to manipulating strings is to concatenate two strings together. For this, you don’t even need to use a function — use the ampersand (&) character. Listing 1 demonstrates string concatenation.

Listing 1: A demonstration of string concatenation.

Sub StringConcatenation()
Dim sFirstName As String
Dim sLastName As String
Dim sFullName As String

sFullName = sFirstName & " " & sLastName
Debug.Print "His name is " & sFullName
End Sub
— The output of this listing is: —
His name is Ronald McDonald
His name is Ronald McDonald

After concatenation, the other basic needs relate to simple string modification such as stripping characters from the beginning or end of a string. The following table documents the basic string modification functions. These functions are demonstrated in Listing 2.

Function Name and Purpose

Left (string, n) Returns the n leftmost characters from a string
Right(string, n) Returns the n rightmost characters from a string
Mid (string, starting at, n) Returns n characters from a string starting with the character in the "starting at" position
LTrim (string), RTrim (string), Trim (string) Removes leading (LTrim), trailing (RTrim), or leading and trailing (Trim) white space
LCase (string), UCase (string) Converts a string to lower case (LCase) or upper case (UCase)

Listing 2: A demonstration of string manipulation.

Sub StringManipulation()

' Using LCase and UCase
Dim sMixedCase As String
sMixedCase = "New York, NY"
Debug.Print UCase(sMixedCase)
Debug.Print LCase(sMixedCase)
End Sub

— The output of this listing is: —
The short zip code is: 55021
The local prefix is: 555
The last four digits are: 1234
Using LTrim:***Interesting Text ***
Using RTrim:*** Interesting Text***
Using Trim:***Interesting Text***
NEW YORK, NY
new york, ny

The ability to employ basic string manipulation opens up a world of possibilities beyond what you can achieve with simple macro recording. Next week I’ll continue this discussion by explaining other text manipulation functions and techniques.

Referring to the Essential Office Programming section of your most recent news letter regarding Application.ScreenUpdating…
I discovered this handy command quite awhile ago while working on large spreadsheets. The performance gain, as was pointed out, was enormous. My problem is, how does the user know that the macro is doing something? If the macro takes too long to run, the user may get impatient and try to terminate the macro or the application.

In the past, I have taken a bit of a performance hit to highlight the first cell of the row the macro is working on (or every nth row if you want to write an if/then statement). This allows the user to know something is happening without having to show every update.

Is there a better way to do this? Is there a way to display and update a progress box while still allowing the macro to run in the background?

You bet there is, Mark. Thanks for the question. This week Steve provides the answer.

- - -

A couple of weeks ago, I discussed the use of Application.ScreenUpdating in Excel to improve the performance of your macros and prevent screen flicker while your macro executes. When you turn screen updating off, it is helpful to provide some sort of feedback to the user so that they know that their computer isn’t locked up.

The method I prefer to use is using Application.StatusBar, which allows you to change the information appearing in the status bar. While the visibility of the status bar can be changed by the user, it is shown by default and in my experience, very few people ever hide it. It is a very non-intrusive way to display progress information.

While some programmers occasionally worry that “my users won’t notice it”, trust me -– they will. Based on solutions I’ve deployed, I’ve never had any feedback to the contrary. When it comes to progress information, subtle is good.

One of the reasons subtle is good when it comes to progress information is that providing progress information has a performance cost. If the reason you are turning screen updating off is to maximize performance, you probably don’t want to implement a progress information system that consumes all of the performance gain. The key is to find a refresh rate that provides reasonable progress information without a noticeable impact on performance.

Listing 1 provides an example of how to use Application.StatusBar in a common scenario –- providing progress information as you process individual rows in Excel.

Listing 1: A demonstration of Application.StatusBar

Sub StatusBarExample()
Dim lRow As Long
Dim ws As Worksheet
Dim lFrequency As Long

' Turn screen updating on and reset the status bar
Application.ScreenUpdating = True
Application.StatusBar = False
Set ws = Nothing
End Sub

To experiment with the performance impact of using Application.StatusBar, run the StatusBarExample a few times with different values for lFrequency. For example try 10, 100, and 1000. This example uses the Mod function to determine if the status bar should be updated. Mod divides two numbers and returns the remainder of the division.

Since you can write arbitrary text to the StatusBar, you can use lots of other schemes besides rows. For example, a batch processing routine may use the filename of the file it is currently processing. A routine that harvests information from numerous worksheets may display the name of the current worksheet. A process that reads data from a database may display a primary key or other identifying attribute (perhaps combined with a frequency modifier such as every nth row).

In summary, Application.ScreenUpdating and Application.StatusBar are very complimentary when used together to maximize the performance of a macro while providing some basic progress information so that the computer doesn’t appear locked-up.

As an example, consider Listing 1. This is a macro I recorded in Microsoft Word to insert a picture and add an orange border to it. If you always add the same picture with the same color borders, perhaps this macro would be useful. However, it would be much more useful and efficient if you modified this macro so that it could be used in more situations. For example, maybe you want to specify which file to add and what color the borders should be.

Listing 1: A simple macro to insert a picture in Word

Sub Macro1()
'
' Macro1 Macro
' Macro recorded 2/21/2007 by Steve Hansen
'
' Note the reference to a hard-coded file name – you should update this
Selection.InlineShapes.AddPicture _
FileName:= "C:\DSC00007.JPG", _
LinkToFile:=False, _
SaveWithDocument:=True

With Selection.InlineShapes(1)
With .Borders(wdBorderLeft)
.LineStyle = wdLineStyleSingle
.LineWidth = wdLineWidth050pt
.Color = wdColorOrange
End With
With .Borders(wdBorderRight)
.LineStyle = wdLineStyleSingle
.LineWidth = wdLineWidth050pt
.Color = wdColorOrange
End With
With .Borders(wdBorderTop)
.LineStyle = wdLineStyleSingle
.LineWidth = wdLineWidth050pt
.Color = wdColorOrange
End With
With .Borders(wdBorderBottom)
.LineStyle = wdLineStyleSingle
.LineWidth = wdLineWidth050pt
.Color = wdColorOrange
End With
.Borders.Shadow = False
End With
With Options
.DefaultBorderLineStyle = wdLineStyleSingle
.DefaultBorderLineWidth = wdLineWidth050pt
.DefaultBorderColor = wdColorOrange
End With
End Sub

You can think of arguments as variables that you define in the declaration of a procedure (the Sub or Function statement) with an added twist — other procedures that call the procedure can specify the value of these variables.

Listing 2 shows a modified version of Listing 1 that uses arguments to specify the filename of the image to add as well as the color of the borders. I also included a procedure named AddTestImage that demonstrates how to call another procedure that uses arguments. This procedure displays a dialog box that prompts the user to select an image to add.

Listing 2: A simple macro to insert a picture in Word with arguments

Sub AddTestImage()
Dim dlgOpen As FileDialog

With Selection.InlineShapes(1)
With .Borders(wdBorderLeft)
.LineStyle = wdLineStyleSingle
.LineWidth = wdLineWidth050pt
.Color = clrColor
End With
With .Borders(wdBorderRight)
.LineStyle = wdLineStyleSingle
.LineWidth = wdLineWidth050pt
.Color = clrColor
End With
With .Borders(wdBorderTop)
.LineStyle = wdLineStyleSingle
.LineWidth = wdLineWidth050pt
.Color = clrColor
End With
With .Borders(wdBorderBottom)
.LineStyle = wdLineStyleSingle
.LineWidth = wdLineWidth050pt
.Color = clrColor
End With
.Borders.Shadow = False
End With
With Options
.DefaultBorderLineStyle = wdLineStyleSingle
.DefaultBorderLineWidth = wdLineWidth050pt
.DefaultBorderColor = clrColor
End With
End Sub

Using arguments is an essential concept to learn in order to start building more elaborate solutions instead of what you create simply by recording macros. As you can see here, it is relatively simple to add arguments to a recorded macro so that you can use it in more situations.

I’ll leave it as an exercise for you to figure out how to simplify the AddImage procedure even more. Here are a couple of clues: you can break it up into multiple procedures that use arguments and the AddImage has extra “baggage” that you can get rid of.