Report scripts

A report script belongs to an individual report design. It runs when that report’s data and output are calculated — in the Administration, for a supervisor or in an automatic report. It is separate from the agent script and script code in a flow.

Expressions and calculated fields are sufficient for many calculations. Use a script when a calculation needs to react to an event or perform several steps. Some supplied templates already calculate values this way.

Checking the language and existing code

1. Open the report design in the report designer. Designing requires the permissions described under Report designs.
2. Select the report itself, for example through the Report Explorer.
3. Check Script Language under Properties. The examples below use C# or Visual Basic; use only the version that matches the selected language.
4. Switch to Scripts at the top right or press F6. Check whether the design already contains code before replacing anything.

The script language applies to the entire design. Changing it does not automatically translate existing code. The supplied Agent report base template contains Visual Basic code; retain its language setting with it.

Assigning events

A script function runs only after it is assigned to the corresponding event of an element. The function name alone does not establish that connection.

• On the Scripts page, select Control: and Event:.
• Alternatively, select an element, open its Scripts under Properties and choose (New) for the required event. The designer generates the appropriate function body.
• Use that body instead of copying parameters and names from a different event. Bands, labels and calculated fields have different tasks.

An event can run repeatedly for many data rows or output elements. Do not assume a single call per report. A self-incrementing counter or a global variable is not a reliable substitute for the designer’s summaries.

Example: conversation time in minutes

This example adds conversation time in minutes to a list of conversations. TotalConnectDuration contains seconds — see Statistics fields.

1. In the Field List, add a calculated field named ConversationMinutes and assign it to the same query as TotalConnectDuration.
2. Do not add another calculation to its Expression. The event performs the calculation.
3. Under Scripts › GetValue, create a function for this calculated field. Keep the name generated by the designer; in this example it is CalculateConversationMinutes.
4. Add the calculation using the version for your script language.

C#:

using System;
using DevExpress.XtraReports.UI;

private void CalculateConversationMinutes(object sender, GetValueEventArgs e)
{
    const string durationColumn = "TotalConnectDuration";
    const double secondsPerMinute = 60.0;
    const int decimalPlaces = 1;
    object duration = e.GetColumnValue(durationColumn);
    if (duration is null || duration == DBNull.Value)
    {
        e.Value = default(double);
        return;
    }

    e.Value = Math.Round(Convert.ToDouble(duration) / secondsPerMinute, decimalPlaces);
}

Visual Basic:

Private Sub CalculateConversationMinutes(ByVal sender As Object, ByVal e As DevExpress.XtraReports.UI.GetValueEventArgs)
    Dim duration As Object = e.GetColumnValue("TotalConnectDuration")
    If duration Is Nothing OrElse duration Is System.DBNull.Value Then
        e.Value = 0.0
        Return
    End If

    e.Value = System.Math.Round(System.Convert.ToDouble(duration) / 60.0, 1)
End Sub

5. Drag the calculated field onto a label in the Detail band.
6. Click Validate and open Preview for a period that contains data.
7. Check a known row: 90 seconds produce 1.5 minutes; an empty database value produces 0. Then save the design.

The event assignment must use exactly the function’s name. If you rename a function in the code, update its assignment under Scripts › GetValue too.

Validation and troubleshooting

Validate checks the script code. Successful validation confirms compilation; it does not prove that the script runs correctly for every data row. Open Preview afterwards.

The report script is saved with the design. For an automatic report, the required code must therefore be in the design being used; code from an agent script does not run with it.