Syntax

objHandler=objAuto.EventsHandler
objAuto.EventsHandler=objHandler

Gets

VOID if events are not handled.

Instance of parent script which handles events generated by automation object.

Sets

VOID to stop handling events.

Instance of parent script which will handle events generated by automation object.

Description

Use EventsHandler property to set a handler for Automation events generated by the wrapped Automation object.

Use ObjectBrowserXtra to see which Automation objects support events. Any Automation object may provide an outgoing interface describing which events it can fire.

After EventsHandler property is set to a valid parent script instance, wrapper starts listening for events. Once a particular event occurs, wrapper tries to call a corresponding method of the attached parent script instance. Event parameters are passed as Lingo property list. Using Lingo list allows event handler to return values via parameters passed by reference.

The code for event handler parent script may look like:

-- Sample EventHandler parent script
on new me
  return me
end

on SomeEventName me, argsList
  arg1=argsList[#ArgName1]
  arg2=argsList[#ArgName2]
  put "SomeEventName fired with arg1="&arg1&&"arg2="&arg2
  argsList[2]=SomeNewValue
end

on IncomingEvent me, event, args
  put event,args
end

Events handler parent script gets every event twice. The first event is sent in a direct form:
on eventName me, argsList
Then the universal handler is called:
on IncomingEvent me, EventSymbol, argsList
This improvement helps discovering what is sent by a COM Automation object. Note: IncomingEvents gets argsList modified by the first handler (if any).

Sample

Sample below demonstrates using events with ADODB.Connection object:

-- *******************************************************
-- Here is the code for EventsHandler parent script
on new me
  return me
end

on IncomingEvent me, event, args
  put event,args
end

on ConnectComplete me, args
  pError=args[1]
  adStatus=args[2]
  pConnection=args[3]

  put "ConnectComplete"
  if(adStatus<>1) then alert pError.Description
end

on Disconnect me, args
  adStatus=args[1]
  pConnection=args[2]

  put "Disconnect"
end

on ExecuteComplete me, args
  RecordsAffected=args[1]
  pError=args[2]
  adStatus=args[3]
  pCommand=args[4]
  pRecordset=args[5]
  pConnection=args[6]

  put "ExecuteComplete"
end

on InfoMessage me, args
  pError=args[1]
  adStatus=args[2]
  pConnection=args[3]

  put "InfoMessage"
end

on WillConnect me, args
  ConnectionString=args[1]
  UserID=args[2]
  Password=args[3]
  Options=args[4]
  adStatus=args[5]
  pConnection=args[6]

  put "WillConnect"

  -- Creating new connection string
  cnnStr="Provider=Microsoft.Jet.OLEDB.4.0;" -- Microsoft Jet provider for MS Access databases
  cnnStr=cnnStr&"Data Source=D:\Temp\TestDB.mdb;"
  cnnStr=cnnStr&"Mode=Read|Write;"
  
  -- return it to the connection object via referenced parameter
  args[1]=cnnStr
end

on WillExecute me, args
  Source=args[1]
  CursorType=args[2]
  LockType=args[3]
  Options=args[4]
  adStatus=args[5]
  pCommand=args[6]
  pRecordset=args[7]
  pConnection=args[8]

  put "WillExecute"
end

-- End of the code for EventsHandler parent script
-- *******************************************************

Name this script as "ConnectionEvents". Then try to execute following lines right in Director's messages window:

  -- Setting debug mode to true
  xtra("VbScriptXtra").Init(true)

  -- Creating an instance of the ADODB.Connection object
  cnn=createObject(xtra "VbScriptXtra","ADODB.Connection")

  -- Creating an instance of the events handler parent script
  evnts=new(script"ConnectionEvents")

  -- Attaching handler to a wrapper
  cnn.EventsHandler=evnts

  -- Opening connection without explicitly specifying connection params
  -- Connection string should be set by the events handler
  cnn.Open()
  
  cnn.Close()

To get more information about ADO events you may use ObjectBrowserXtra or see ADO documentation.