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 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 a 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 functionwithout parameters, which is automatically called by the runtime system, if itsassociated event occurs.
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. |
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;