Script designer

1. General information

• A script is a programmatic code executed on the server side.

• Scripts can be executed:
  • in server events of edit forms,
    • OnBeforeOpen – executed before opening an edit form after clicking “Save and new”,
    • OnAfterOpen – executed after an edit form is opened,
    • OnBeforeSave – executed before a record is saved to the database,
    • OnAfterSave – executed after a record is saved to the database,
    • OnBeforeDelete – executed before a record is deleted from the database,
    • OnAfterDelete – executed after a record is deleted from the database,
  • after clicking a button in an edit form,
  • after clicking a button on a view page,
  • when attempting to create a new record from the “TimeTable” or “Planner” controls.

• A reference to a script is always part of the configuration dialog of a control.
  • Most commonly this is the “ActionButtons” control (edit form server events) or the “Button” control (buttons in edit forms and view pages).
  • The link labeled “Edit script (number of script lines)” opens the script designer.

• A script consists of numbered lines evaluated sequentially from top to bottom.

• Each script line represents a single instruction.

• NET Genium scripts do not support program blocks.

1.1. Core script commands

• Variable declaration
  • Defines the data type of a script variable.
  • If the variable already exists or contains a value, its type is changed and its value is set to database “null”.

• Loading a value from a database query
  • Loads a value from a database query into a script variable or a form control.
  • Existing variable type and value are overwritten.

• Saving variable values back to the database
  • Writes variable values back to the database source.
  • The variable must not change the number of values it contains.

• Loading multiple values from a database query
  • Loads values from multiple columns into variables or form controls.

• Loop
  • Iterates over values of a controlling variable using the “Next…” delimiter.
  • If the variable contains no values, the loop is skipped.
  • During iteration, variables behave as single-value variables.
  • Null values are automatically skipped.
  • The primary key “id” is recommended as the controlling variable.

• Assignment
  • Assigns a single value or a mathematical expression to a variable or control.
  • For value arrays, the operation is applied to all elements.

• Comparison
  • Compares variable values or user-entered values.

• Additional commands
  • Jump to line
  • Raise interruption
  • Send e-mail
  • Delete database records
  • Redirect to an edit form (available only in OnBeforeOpen, OnAfterSave, OnAfterDelete)
  • Create new database records
  • Save one or more values to the database
  • Comment (including calls to external functions)

1.2. Nature of the scripting language

• NET Genium scripting is a declarative, line-oriented language.
• It does not support code blocks, branching structures, or complex algorithms.
• Complex logic must be implemented using external functions written in C#.

1.3. Running scripts outside the web interface

• Scripts assigned to buttons on view pages can be executed externally using the “RunScript.exe” utility.
• The utility is located in the “NETGenium\bin” directory on the server.

1.4. Script errors and interruptions

• Script execution may fail due to syntax errors, conversion errors, database write errors, or explicit interruptions.
• In all cases, execution is terminated, control returns to the original context, and an error message is displayed.
• For “OnBeforeSave” and “OnBeforeDelete” scripts, interruption prevents saving or deleting the record.

1.5. Scope of the scripting language

• The NET Genium scripting language is a closed and limited language designed exclusively for controlling application logic on the server side. A script may use only the variables, commands, operators, server functions, and external functions explicitly described above. Any other constructs, functions, operators, data types, return values, code blocks, or language elements are not supported and cannot be used in scripts. If the required functionality cannot be implemented using the available script commands, variables, and server functions, it must be implemented as an external function written in the C# programming language.

2. Script designer dialog

2.1. Drop-down list “Enter the command…”

• A drop-down list with a selection of the type of command that will be inserted into the script at the selected location.
  • 1. Declare a variable
  • 2. Add a value from the query
  • 3. Save the variable back to the database
  • 4. Add multiple values from the query
  • 5. Cycle
  • 6. Add a value
  • 7. If (expression) assign a value
  • 8. If (composite expression) assign a value
  • 9. Go to the line
  • 10. If (expression) go to the line
  • 11. If (compound expression) go to the line
  • 12. Raise Exception (Interrupt)
  • 13. If (expression) raise an exception
  • 14. If (compound expression) raise an exception
  • 15. Send email
  • 16. If (expression) send an e-mail
  • 17. If (compound expression) send e-mail
  • 18. Delete entry
  • 19. If (expression) delete the record
  • 20. If (compound expression) delete the record
  • 21. New record
  • 22. If (expression) a new record
  • 23. If (compound expression) a new record
  • 24. Save the value to the database
  • 25. If (expression) store the value…
  • 26. If (compound expression) store the value…
  • 27. Store multiple values in a database
  • 28. If (expression) save more…
  • 29. If (compound expression) save more…
  • 30. Comment

2.2. Drop-down list “Variables”

• Drop-down list with a selection of variables that will be available in the script for storing values. These variables can be used on individual lines of the script.
• A detailed description of the variables is provided in the separate Variables guide.

2.3. Drop-down list “Functions”

• Drop-down list with a selection of server functions that can be called on individual lines of the script.
• A detailed description of the server functions is provided in the separate Server functions guide.

2.4. Drop-down list “Values”

• A drop-down list with a selection of database control identifiers that can be used on individual lines of the script.

2.5. Link “Dictionary...”

• The dictionary displays a list of comments and interrupts used across all scripts throughout the application that relate to the following types of commands:
  • The “message” parameter of the “SCHEDULEBACK” server function in the script comment
  • The “message” parameter of the “TEFUIG” server function in the script comment
  • The “message” parameter of the “TESUIG” server function in the script comment
  • The “message” parameter of the “WRITEMESSAGE” server function in the script comment
  • Script abort
• Dictionary search is used to design the correct form of user messages and to maintain the consistency of nomenclature throughout the application.

2.6. Link “Change tracking...”

• Change tracking displays a detailed report with all script changes made by individual users.

2.7. Link “Statistics…”

• The statistics display aggregated information about the usage of the control associated with this script across the entire application.
• Using the “Statistics” link opens a detailed report of all places where the control is used or referenced, including the ability to open the settings of that location or control.

2.8. Link “Logging…”

• Using the “Logging” link displays a detailed report containing records of the script execution. The report includes information on:
  • the date and time when the script was executed,
  • the user who executed the script,
  • the script processing time,
  • the start date and time of the processing, and
  • the end date and time of the processing.

• For logging to function correctly, logging must be enabled in the NET Genium modify on the “Other” tab, either as “To database” or “To database and disk”, A detailed description is provided in the separate guide NET Genium settings.
• The minimum displayed script-processing time is set by default to 0 milliseconds, meaning that all script-execution records are shown, including those whose processing time was 0 ms. This minimum time can be increased or decreased by modifying the “mintime” parameter in the report URL.
• The number of displayed records is limited by default to 100 entries. This number can be manually increased or decreased by modifying the “maxrows” parameter in the report URL.

2.9. “Run script” button

• The “Run script” button is used to run the script in test mode.
• Running a script simulates the progress of script processing, but does not store any values in the database or delete any records from the database.
• External functions called from the script in test mode are not executed – the value “true” in the “test” parameter is passed to the external function:

using System;

namespace NETGenium
{
  public class ExternalFunctions
  {
    public static string ngef(string id, string[] args, bool test, DbCommand cmd, DbConnection conn)
    {
      if (test) return "";

      switch (id)
      {
        // case "MyFirstFunction": return MyFirstFunction();
        default: return conn == null ? "" : conn.ExternalFunctionNotFound(id, cmd);
      }
    }
  }
}

2.10. “Save” button

• Save changes to the script.

2.11. “Save and continue editing” button

• Save changes to the script and leave the script open for further editing.