The DTS Package object raises events, allowing client application response to execution state change as the referenced package executes. For example, under some circumstances the object raises the OnProgress event indicating a percentage of a task completed. The application can respond to the event by, for example, updating a control indicating percentage complete.
COM objects raising events are called connectable objects. The object exposes an IConnectionPointContainer interface through which an application can make visible its response mechanisms to events raised.
Automation controllers hide much of the complexity of event handling. For Microsoft® Visual Basic™, the application makes event handling subroutines or functions through use of the WithEvents keyword on object dimensioning. For a C++ application, a class inherited from a COM server-defined, sink interface implements event handling. The application uses the IConnectionPointContainer and IConnectionPoint interfaces to make the implementation visible to the COM server.
Visual Basic implements the keyword WithEvents on object variable dimensioning statements to enable application handling of events.
WithEvents imposes restrictions on object dimensioning. An object variable allowing event handling must be declared within an object module, such as that associated with a Visual Basic form. Further, WithEvents restricts the use of the keyword New, disallowing its use for shorthand object dimensioning and creation. This Visual Basic statement is illegal:
Private WithEvents oPackage as New DTS.Package
Object dimensioning must be accomplished in a separate step, as in:
Private WithEvents oPackage as DTS.Package
Set oPackage = New DTS.Package
When a DTS application indicates that it will handle events raised by an instance of a Package object, the application must supply subroutines to handle every event raised by the object. You must ensure that executable creation does not inadvertently remove subroutines handling an event.
For example, an application may want to respond to only the OnError event of the Package object, ignoring all other events. You can implement the handlers for events not handled using a single, processor-inexpensive statement as shown below:
Private Sub oPackage_OnFinish(ByVal EventSource As String)
Exit Sub
End Sub
Private Sub oPackage_OnProgress(ByVal EventSource As String,
ByVal ProgressDescription As String, ByVal PercentComplete As Long,
ByVal ProgressCountLow As Long, ByVal ProgressCountHigh As Long)
Exit Sub
End Sub
Private Sub oPackage_OnQueryCancel(ByVal EventSource As String,
pbCancel As Boolean)
Exit Sub
End Sub
Private Sub oPackage_OnStart(ByVal EventSource As String)
Exit Sub
End Sub
You can then handle the OnError event, displaying a message box as shown below:
Private Sub oPackage_OnError(ByVal EventSource As String,
ByVal ErrorCode As Long, ByVal Source As String,
ByVal Description As String, ByVal HelpFile As String,
ByVal HelpContext As Long,
ByVal IDofInterfaceWithError As String, pbCancel As Boolean)
MsgBox(Description)
pbCancel = True
End Sub
For more information about Visual Basic support for events, see your Visual Basic documentation.
Note As indicated earlier, Visual Basic allows application response to raised events. To support DTS event handling, Visual Basic requires that the project reference the DTS object library. Event handling is not supported when a DTS Package object is created by using the CreateObject function. Your Automation controller may impose similar restrictions.
Visual Basic is apartment-threaded while DTS is free-threaded. Therefore the DTSPackage could send multiple simultaneous events to Visual Basic and Visual Basic would not be able to handle them. To prevent this, set the ExecuteInMain thread of each step in the package to True.
For connectable objects, COM defines the responsibilities for servers and clients. A connectable object exposes the IConnectionPointContainer interface through which the client obtains the IConnectionPoint interface. The client implements functions to handle callbacks from the server, called a sink. Using the IConnectionPoint interface, the client notifies the server of its ability to handle callbacks, providing its sink implementation as an argument.
The client-implemented sink is a COM object. As with any COM application development task, implementing a sink for a Package object is fairly painless when using C++. The client application defines a class, inheriting from the IDTSPackageEvents interface, then implements members to handle the callbacks of interest.
Note The details of COM connectable object implementation is a topic beyond the scope of this documentation. For more information about COM connectable objects, IConnectionPointContainer, and IConnectionPoint, see a reliable COM/OLE reference.