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;