SDK - Creating a Custom Event Handler

  • KM508061
  • 20-Sep-2008
  • 08-Jun-2010

Archived Content: This information is no longer maintained and is provided "as is" for your convenience.


This document provides advice and examples of a custom event handler using the TRIM SDK


Creating a Custom Event Handler

Return to SDK Samples

The following code sample takes you through the basic ins and outs of creating custom event processor code. This includes writing the code and installing the resulting DLL on the event server. Before you get started, please make sure you understand the basics by reading the Event Processor article.


  • The Event Processor add-in should be coded in Visual Basic 6, Delphi, or C++. Essentially any language that supports OLE2 Automation. This sample uses VB6.
  • An in-process Event Procedure will be created as an ActiveX DLL.
  • Code references TRIM SDK (trimsdk.dll).

Code Breakdown

  • Creating an Event Processor add-in follows some basic skeleton code. This is the minimum you need to work with the event processor.
Option ExplicitImplements TRIMEventProcessor Private Property Get TRIMEventProcessor_ErrorMessage() As String End Property Private Sub TRIMEventProcessor_ProcessEvent( _        ByVal ForDatabase As TRIMSDK.IDatabase, _        ByVal EventType As TRIMSDK.evEvents, _        ByVal ProcessType As TRIMSDK.epEventProcessType, _        ByVal MachineName As String, _        ByVal LoginName As String, _        ByVal LoginUri As Variant, _        ByVal EventDate As Date, _        ByVal EventTimeZone As Long, _        ByVal EventForObjectType As TRIMSDK.btyBaseObjectTypes, _        ByVal EventForObject As Variant, _        ByVal EventForObjectName As String, _        ByVal RelatedObjectType As TRIMSDK.btyBaseObjectTypes, _        ByVal RelatedObjectUri As Variant, _        ByVal RelatedObjectName As String, _        ByVal EventExtraDetails As String) On Error GoTo err_TRIMEventProcessor'your code goes hereExit Suberr_TRIMEventProcessor:'error handling goes hereEnd Sub

Implementing the TRIMEventProcessor does most of the work. You just have to handle the events as they happen. The evEvents enum gives you a list of all the events that can be captured by the event processor. These events will drive how you code behaves.

  • The sample I’m sharing is based off a record being created or modified. Therefore, I want to know if it’s a record. I check the EventForObjectType to see if it’s a record (btyRecord; all object types are found in btyBaseObjectTypes enum). I am only interested in the evObjectAdded and the evObjectModified events for the record. In the below code, I’m already inside TRIMEventProcessor_ProcessEvent:
...    Set myDB = New TRIMSDK.Database    If EventForObjectType = btyRecord Then        If (EventType = evObjectModified) Or (EventType = evObjectAdded) Then            'grabbing database information from the initiating event            myDB.Id = ForDatabase.Id            If myDB.IsValid Then                Call myDB.Connect             Else               GoTo err_TRIMEventProcessor            End If...
  • Next I want to instantiate the record that was created/modified and find out its record type:
...                        Dim myRecord As TRIMSDK.Record            Set myRecord = myDB.GetRecord(EventForObject)            If Not myRecord Is Nothing Then                 If myRecord.RecordType.Name = "Document" Then...
  • Now that I’ve made it through all of my preliminary checks, I want to close any open actions on my record. I simply check to see if a Current Action exists, and then loop through any that remain:
...                        If Not CStr(myRecord.CurrentAction) = "" Then                            'The loop will close any remaining actions                            allComplete = False                            Do Until allComplete = True                                myRecord.CompleteCurrentAction                                If CStr(myRecord.CurrentAction) = "" Then                                    allComplete = True                                End If                            Loop                            If Not myRecord.Verify(True) Then                                GoTo err_TRIMEventProcessor                            Else                                myRecord.Save                            End If                        End If...
  • Next I want to close my database connection and close all my IF statements:
...                            End If                myDB.Disconnect                End If            End If        End If    End If...
  • Finally, if any errors occur, I want to send them to the err_TRIMEventProcessor:
...Exit Suberr_TRIMEventProcessor:    'you can do some logging here, or any other error handling.    'In the example I'm just closing down the database connection    If myDB.IsConnected Then        myDB.Disconnect    End IfEnd Sub

And that’s it, a simple Event Processor add-in that checks for a record that has been created or updated, and closes all associated actions. What’s next you ask? Now we need to make the code a DLL (In VB, go to File>Make xxx.dll) and install it on the event server.

Installing the Event Processor Add-In

Register the DLL

To do this, you must be on the physical server where the Workgroup Server and more importantly the Event Server live. Go to Start>Run and type cmd. You will get the dos window. Inside the dos window, you will need to type in the following:

regsvr32 “<path>\ <filename>.dll”
A popup will confirm that this registered properly.

Add to TRIM Enterprise Manager

Now that it’s registered, we add it into the TEM. So, from inside there, find the active Event Server and right click and go to Properties. In the Configure Processes tab, you will see at the bottom a check box for User Defined. Select it, and enter the text: <project name>.<class module>
Click OK, and then you will get popups confirming the add-in and telling you that you need to restart the services for it to take effect.

Restart the Services

Now you must restart the services. Go to start>programs>administrative tools>Services. Find the TRIM Event, Sync, and Workgroup services. Press stop on the Synch service, and it will prompt you to stop the rest. After they’ve all stopped, start them up again. Sometimes the event service takes a while.

Once all started, you can test your code. If you have good logging (like creating a text file and posting code) you can view that to see success. If not, wait for your event to process (you can monitor this in the event processor), and see if the expected behavior occured.