FB TraceManager 2 - Documentation

Event Processing - Writing Rule Script Code

Event Processing - Writing Rule Script Code

Previous topic Next topic  

Event Processing - Writing Rule Script Code

Previous topic Next topic  

It is beyond the scope of this chapter to teach you the Pascal syntax, but with the following simple examples, it should be fairly easy to adjust your rule code properly. A  good starting point is to have a look on the few pre-installed code catalog items.

 

After creating a new event rule, you start with an empty begin/end block.

 

begin
  // Add your code here ...
end.

 

Available functions and variables

 

The available functions and variables depend on the chosen rule type. All FB TraceManager related variables and functions start with fbtm_ in its name. Further naming prefixing conventions are as followed:

 

fbtm_c_...: Constant value, e.g. column names of the parsed trace data grid.
fbtm_r_...: Return variable value, which then gets assigned back in the FB TraceManager code. E.g.: background color of a cell.
fbtm_v_...: Variable, e.g. concrete values of parsed trace data columns. As an example: fbtm_vExecutionTime=100.

 

Some concrete examples will give you a better idea of the hereby chosen variable names:

 

fbtm_cFieldName_ExecutionTime: Name of the execution time column in the parsed trace data grid. The following IF condition checks whether the current cell/column is the execution time column.

 

if fbtm_vGridColumnName = fbtm_cFieldName_ExecutionTime then
begin
  ...
end;

 

 

fbtm_rGridCellBackgroundColor: Return value for assigning a certain background for a cell. This variable is available in the OnTraceDataParsedGridCellColoring rule type. The following example applies the background cell color red, if the execution time is greater than 5000 milliseconds.

 

if (fbtm_vFieldValue_ExecutionTime > 5000) then
begin
  fbtm_rGridCellBackgroundColor := clRed;
end;

 

As there is no check on a particular field name when assigning the background color, the entire row in the parsed trace data grid will be painted with the given color. To assign the background color only to the currently processed grid cell, this could look like:

 

procedure SetCellColor;
begin
  if Pos('NATURAL', fbtm_vFieldValue_ExecutionPlan) > 0 then
  begin
    if fbtm_vGridColumnName = fbtm_cFieldName_ExecutionPlan then
      fbtm_rGridCellBackgroundColor := clRed;
  end;
end;
 
begin
  SetCellColor;
end.

 

The example above will set the background color red for the execution plan column only, if the traced execution plan has the phrase "NATURAL" included. As you can see in this example, a script isn't limited to the begin/end block, but also can contain procedure/function declarations.

 

Hint: The availble Color Selector dropdown-box makes choosing a proper color constant easier! Simply put the cursor in the code editor and chose a color from the Color Selector. The corresponding color constant then gets inserted at the current cursor position.

 

 

fbtm_rGridCellFontColor: Return value for assigning a certain font color for a cell. This variable is available in the OnTraceDataParsedGridCellFormatting rule type. The usage is pretty much the same as in the background cell color example.

 

 

fbtm_rIsGridCellFontBold: Return value (True|False), if the cell font color should be bold. This variable is available in the OnTraceDataParsedGridCellFormatting rule type. Example:

 

procedure SetCellFormat;
begin
  if Pos('RETAIN', fbtm_vFieldValue_EventName) > 0 then
  begin
    if fbtm_vGridColumnName = fbtm_cFieldName_EventName then
      fbtm_rIsGridCellFontBold := True;
  end;
end;
 
begin
  SetCellFormat;
end.

 

The example above will display the content of the event name column in bold style, if the event name includes the phrase "RETAIN" (e.g. to spot commit/rollback retaining events).

 

Similar return variables are: fbtm_rIsGridCellFontItalic, fbtm_rIsGridCellFontStrikeOut and fbtm_rIsGridCellFontUnderline

 

 

fbtm_ShowAlertWindow(AText: String; ACloseDelay: Integer = 5000): Calls an alert window with the given text and an optional close delay parameter in milliseconds. This method is available in the OnShowAlertWindow rule type. The following example shows an alert window for 10 seconds, if the execution time of a statement exceeds 5 ms.

 

var
  alertText: TStrings;
begin
  if (fbtm_vFieldValue_ExecutionTime > 5) then
  begin
    alertText := TStringList.Create;
    try
      if fbtm_vGridColumnName = fbtm_cFieldName_ExecutionTime then
      begin
        alertText.Add(Format('Server: %s', [fbtm_vServerName]));
        alertText.Add(Format('Project: %s', [fbtm_vProjectName]));
        alertText.Add(Format('Row#: %d', [fbtm_vGridRowIndex]));
        alertText.Add(Format('Execution time: %d ms', [fbtm_vFieldValue_ExecutionTime]));
 
        fbtm_ShowAlertWindow(alertText.Text, 10000);
      end;
    finally
      alertText.Free;
    end;
  end;
end.

 

As you can see, even more complex Pascal classes TStrings, TStringList etc. are available for writing script code. The alert window looks like that at run-time:

 

fbtm_eventprocessing_alertwindow

 

Hint: If you are using a ACloseDelay of 0, then the alert window doesn't close automatically. It stays open until you click the close button in the right upper corner of the window.

 

 

fbtm_SendEmail(AAddressTO, AAddressCC, AAddressBCC, ASenderEmail, ASubject, ABody: String): Sends an email to various recipients with the given email subject and message. You can provide a comma separated list of recipients in the AAddressTO, AAddressCC, AAddressBCC parameters. The following example sends an email, if the execution time of a statement exceeds 5000 ms. Sending the email will happen in its own dedicated thread.

 

var
  emailBody: TStrings;
begin
  if (fbtm_vFieldValue_ExecutionTime > 5000) then
  begin
    if (fbtm_vGridColumnName = fbtm_cFieldName_ExecutionTime) then
    begin
      emailBody := TStringList.Create;
      try
        emailBody.Add(Format('Server: %s', [fbtm_vServerName]));
        emailBody.Add(Format('Project: %s', [fbtm_vProjectName]));
        emailBody.Add(Format('Row#: %d', [fbtm_vGridRowNumber]));
        emailBody.Add(Format('Execution time: %d ms', [fbtm_vFieldValue_ExecutionTime]));
 
        fbtm_SendEmail (
          'to@to.com'
          , ''
          , ''
          , 'from@from.com'
          , 'FB TraceManager - Notification Email'
          , emailBody.Text
        );
      finally
        emailBody.Free;
      end;
    end;
  end;
end.

 

Important: You first have to provide proper SMTP settings in the Settings dialog!

 

 

fbtm_ExecuteApplication(AFileName, AParameters: String; AHide: Boolean = False): Executes an application provided in the AFileName input parameter with optional arguments in AParameters. Use AHide = True, if you want to hide the executed application when running. Further FB TraceManager execution isn't blocked when using this method. This method is available in the OnExecuteApplication rule type. The following example writes the header page of a Firebird database into a file tourism_headerpage.txt, if the event name contains RETAIN in its name (e.g. the COMMIT_RETAINING trace event).

 

begin
  if Pos('RETAIN', fbtm_vFieldValue_EventName) > 0 then
  begin
    if fbtm_vGridColumnName = fbtm_cFieldName_EventName then
    begin
      fbtm_ExecuteApplication(
        'cmd.exe'
        , '/C "C:\Program Files\Firebird\Firebird_250_3051\bin\gstat.exe" -h localhost/3051:tourism.fdb -user xxx -password xxx > c:\tourism_headerpage.txt'
        , True
      );
    end;
  end;
end.

 

Hint: As shown above, if you want to execute an application with redirecting its output into e.g. a file, you have to use the fbtm_ExecuteApplication in a special way. You don't provide the application filename in the first parameter, instead you need to provide a command-line shell/interpreter (cmd.exe) in combination with providing the full execution command of your application with the /C switch of cmd.exe.

 

 

fbtm_PlayFile(AFileName: String): Plays a .WAV file provided in the AFileName input parameter. While this type of event rule looks a bit childish, it's extremely useful for getting notified, if you are running FB TraceManager in the background with the monitor turned off and speakers turned on. This method is available in the OnPlaySound rule type. The following example plays a sound file alarm.wav in case of an event including RETAIN in its event name.

 

begin
  if Pos('RETAIN', fbtm_vFieldValue_EventName) > 0 then
  begin
    if fbtm_vGridColumnName = fbtm_cFieldName_EventName then
    begin
      fbtm_PlayFile('c:\alarm.wav');
    end;
  end;
end.

 

 

fbtm_PlaySystemSound(ASystemSound: String): Instead of providing a filename, a Windows system sound provided as string in ASystemSound is played. This method is available in the OnPlaySound rule type. Make use of the System sound selector combo-box in the Script Builder area to select a valid system sound as string. The following example plays the Windows system sound for SystemNotification in case of an event including RETAIN in its event name.

 

begin
  if Pos('RETAIN', fbtm_vFieldValue_EventName) > 0 then
  begin
    if fbtm_vGridColumnName = fbtm_cFieldName_EventName then
    begin
      fbtm_PlaySystemSound('SystemNotification');
    end;
  end;
end.

 

 

Compile

 

The script code can be compiled by clicking the Compile button. If there are any errors in the code, a message dialog with the error text of the interpreter is shown. If the compile process was successful, the source code for the selected rule is stored in the database.

 

Hint: You will notice when starting editing source code, the selected rule node on the left is shown in bold font. The node font goes back to normal if the compilation was successful. If you want to move to another rule without compiling previously changed code, a proper confirmation dialog asks you whether you want to discard those changes or not.

 

 

What's next: The next section discusses how to use the Code Catalog.

 

See also

Event Processing Basics

Event Processing Register Event Rule

Event Processing Code Catalog

Browse

Reports

Analysis

 

 

t_rule.htm">Event Processing Register Event Rule

Event Processing Code Catalog

Browse

Reports

Analysis