| Platform SDK: CDO 1.2.1 |
The CDO Library raises exceptions for all errors. When you write Microsoft® Visual Basic® applications that use the CDO Library, use the same run-time error handling techniques that you use in all your Visual Basic applications: the Visual Basic On Error GoTo statement.
Note that the error values and error handling techniques vary slightly depending on whether you are using Visual Basic version 4.0 or older versions of Visual Basic for Applications.
When you use older versions of Visual Basic for Applications, use the Err function to obtain the status code and the Error$ function to obtain a descriptive error message, as in the following code fragment:
' Visual Basic for Applications error handling MsgBox "Error number " & Err & " description. " & Error$(Err)
When you use Visual Basic 4.0, use the Err object’s Number property to obtain the status code and its Description property to obtain the error message, as in the following fragment:
‘' Visual Basic version 4.0 error handling MsgBox "Error " & Err.Number & " description. " & Err.Description
Depending on your version of Visual Basic, the error code is returned as a long integer or as a short integer, and you should appropriately define the value of the error codes checked by your program.
When you use Visual Basic 4.0, the error value is returned as the value of the MAPI HRESULT data type, a long integer error code. When you use earlier versions of Visual Basic, the error value is returned as the sum of decimal 1000 and the low-order word of HRESULT. This is because versions of Visual Basic previous to 4.0 reserve all run-time error values below 1000 for their own errors.
This code fragment checks for an error corresponding to the MAPI error code CdoE_USER_CANCEL, which has the value &H80040113. Visual Basic 4.0 users can check directly for this value. Visual Basic for Applications users check for the value of the low-order word plus decimal 1000. The low-order word is &H0113, or 275, so the value returned by Visual Basic for Applications is 1275.
' demonstrates error handling for Logon
' Function: TestDrv_Util_CreateSessionAndLogon
' Purpose: Call the utility function Util_CreateSessionAndLogon
Function TestDrv_Util_CreateSessionAndLogon()
Dim bFlag As Boolean
On Error GoTo error_olemsg
bFlag = Util_CreateSessionAndLogon()
MsgBox "bFlag = " & bFlag
Exit Function
error_olemsg:
MsgBox "Error " & Str(Err) & ": " & Error$(Err)
Resume Next
End Function
' Function: Util_CreateSessionAndLogon
' Purpose: Demonstrate common error handling for Logon
Function Util_CreateSessionAndLogon() As Boolean
Dim objSession As MAPI.Session
On Error GoTo err_CreateSessionAndLogon
Set objSession = CreateObject("MAPI.Session")
objSession.Logon
Util_CreateSessionAndLogon = True
Exit Function
err_CreateSessionAndLogon:
If Err() = 1275 Then ' VB4.0: If Err.Number = CdoE_USER_CANCEL Then
MsgBox "User pressed Cancel"
Else
MsgBox "Unrecoverable Error:" & Err
End If
Util_CreateSessionAndLogon = False
Exit Function
error_olemsg:
MsgBox "Error " & Str(Err) & ": " & Error$(Err)
Resume Next
End Function
When an error occurs in the MAPI subsystem, the CDO Library supplies the error value returned by MAPI. However, the value can be returned from any of several different levels of software. The lowest level of software is that which interacts directly with hardware, such as a mouse driver or video driver. Higher levels of software move toward greater device independence and greater generality.
The following diagram suggests the different levels of software in Visual Basic applications that use the CDO Library. Visual Basic applications reside at the highest level and interact with the CDO Library at the next lower level. The CDO Library interacts with the MAPI system software, and the MAPI system software interacts with a lower layer of software, the operating system.
Errors can occur at any level or at the interface between any two levels. For example, a user of your application without security permissions can be denied access to an address book entry. The lowest level in this diagram, the operating system, returns the error to the next higher level, and so on, until the error is returned to the highest level in this diagram, the Visual Basic application.
It is often useful to provide a general error handling capability that can display the complete HRESULT or error code value returned by the CDO Library.
For more information about run-time error handling and the Err object, see your product’s Visual Basic documentation. For a listing of CDO Library and MAPI error values, see Error Codes.