Script designer

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.

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)

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#.

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.

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.

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.

1. Script Designer

1.1. 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

1.2. 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 given in the separate Variables manual.

1.3. 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 given in the separate Server functions manual.

1.4. Values

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

1.5. 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.

1.6. Change tracking

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

1.7. Run script

• 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);
      }
    }
  }
}