Event Handler Section

During a script run, it is often desired to have the possibility to execute a portion of BDL code in order to react to one or more particular situations (also known as events). Such a portion of BDL code is called event handler function. A typical task of an event handler function is to e.g. perform clean-up statements after a transaction exit error, or generally catch an error or warning before it gets reported.

BDL offers the possibility to define an event handler function for one of the following set of pre-defined events:

BDL event constant	Description
EVENT_RAISE_INFORMATION	Informational message
EVENT_RAISE_WARNING	Warning message
EVENT_RAISE_ERROR	Error message
EVENT_RAISE_TRANS_EXIT	Transaction exit error
EVENT_RAISE_PROC_EXIT	Process exit error
EVENT_TRANS_BEGIN	Transaction begin (within transaction context)
EVENT_TRANS_END	Transaction end (within transaction context)
EVENT_TRANS_FINISHED	Transaction finished (not within transaction context)
EVENT_SUSPEND	Suspending
EVENT_RESUME	Resuming
EVENT_STOP	Stop
EVENT_CITRIXINTERRUPT	Custom Citrix event (see CitrixAddInterrupt)
EVENT_USER_FINISHED	End of test script

A handler function must be defined in an event handler section. Each event handler section begins with the keyword dclevent. There may be more than one dclevent sections in a BDL translation unit.

From the semantic point of view an event handler can be considered as a function without parameters, which is automatically called by the runtime system, if its associated event occurs.

Syntax

EventSection = "DCLEVENT" { Handler }.
Handler = "HANDLER" ident "<"EventConstant">"
          [ "CONST" ConstDecl ]
          [ "VAR" VarDecl ]
          "BEGIN" StatSeq "END" ident ";"

Section	Description
ident	The name of the function.
EventConstant	One of the above BDL event constants
ConstDecl	The declarations of the function constants.
VarDecl	The declarations of the function variables.
StatSeq	The statements of the function.

Example

dclevent
  handler Handler1 <EVENT_RAISE_ERROR>
  begin
    if GetErrorCode(GetLastError()) = 1060 then
      print("caught HTTP: 1060 - HTML Hyperlink not found");
    elseif GetErrorCode(GetLastError()) = 404 then
      print("caught HTTP: 404 - object not found");
    else
      throw;
    end;
  end Handler1;

dcltrans
  transaction TestTrans
  begin
    ...
  end TestTrans;