Writing data scripts with DundasScript

Contents[Hide]

1. Overview

When it comes to developing scripts in the application, Dundas BI consists of two parts:

  1. On the user interface and user experience level, the scripts are written in JavaScript and typically attached to a triggering action.
  2. On the data level, the scripts are written in DundasScript, which is currently used in bridge parameters, calculated elements, OLAP data connectors, formulas, and script token attributes.

This article provides an overview of the DundasScript engine, including some examples and limitations to be aware of.

2. The DundasScript engine

The DundasScript engine lets you use a scripting language that can be thought of as a subset of the C# programming language, but it shares most of the syntax with other languages, including Java, JavaScript, and C, and supports dynamic types.  

2.1. Syntax

The DundasScript engine syntax is composed of the following supported elements:

  • Keywords:
    break, catch, continue, do, else, false, finally, for, foreach, if, in, is, new, null, return, true, try, var, while
  • Built-in data types:
    bool, byte, char, decimal, double, float, int, long, object, string
    
  • Operators (with the standard order of operations):
    +, -, * , / , (, ), !, %, =, ==, != <, >, <=, >=, +=, -=, *=, /=, ++, --
    

    Including short-circuit evaluation of Boolean expressions, the same as most languages. This applies to both && and || operators.

  • Indexers, to access items in a collection, list, or array.
  • Exceptions, to handle errors when the script does something unsupported:
    string[] parts;
    try { parts = someVariable.Split(); } catch( /* NullReferenceException */ ) { parts = new string[]; } 
    
  • Generics, if a generic type is registered with the engine:
    List myIntList = new List(); myIntList.Sort();
    
  • Access to all of an object's public methods, properties, and fields:
  • Single dimensional arrays (note that inline array initialization isn't supported):
    int[] bunchOfValues = new int[7]; bunchOfValues[0] = 1; bunchOfValues[1] = 1; bunchOfValues[2] = 2; bunchOfValues[3] = 3; bunchOfValues[4] = 5; bunchOfValues[5] = 8; bunchOfValues[6] = 13;
    
  • Both types of comments:
    // Describe your code. /* Comments are useful. */

2.2. Numeric values

Numeric values default to int, or integral numbers. Include the decimal point, or use f or d to explicitly declare numeric literals as float or double values:

  • 12 – integer
  • 12f – floating point
  • 12d – double-precision

As in most programming languages, the division of two integers always results in an integer. For example, the resulting value of r in the  following script is 2.0:

double r = 12 / 5;

Use the following script instead to get the desired result, r=2.4:

double r = 12.0 / 5;

Or:

double r = 12d / 5;

2.3. Features

The DundasScript engine implements a custom interpreter. Although close in syntax with C#, it is a dynamically-typed script language. This results in the following features:

  • You do not need to know the type of an object or cast it to access one of its properties.
  • You can use the var keyword in place of any type name to simplify script.
  • You can call static methods on an instance variable.
  • There is no variable scoping. This means that you can redefine a variable, but note that if you do the previous value will be overwritten/lost. For example:
    // Create a new string: string foo = new string( "Hello world" );
    ...
    if( someCondition ) { // From now on, foo is an int, not a string! int foo = 10; ... } 

2.4. Limitations

The following elements are not supported in DundasScript:

  • Multidimensional arrays.
  • Indexers with multiple parameters.
  • throw statements.
  • Delegates.
  • Multiple variable declarations per line.
  • Creating user-defined events.
  • Nullable types and the ?? operator.
  • Numeric hex literals, such as 0x00.
  • switch, case, and default statements.
  • ref and out parameters.
  • Lambda expressions.
  • The following operators:
    &, |, ^, &=, |=, ^=, >>, <<, >>=, <<=, typeof, sizeof ~x, ++x, --x 
  • The conditional operator (x ? y :z).
  • Array creation using initializer:
    int">"> a = new int[ { 1, 2, 3 }; 

2.5. Multi-line strings

The value of a string variable can span multiple lines using the @ character. For example:

string s = @"Dundas Data Visualization, Inc."

2.6. Standard .NET classes

Only registered classes can be used, providing a sandbox that makes it almost impossible for a script to make your dashboard misbehave or crash. 

The following classes are exposed in the DundasScript engine. They access the .NET classes directly and have not been re-implemented in the engine. All public methods, properties and fields will work as documented at the MSDN site:

  • Array — Provides methods for creating, manipulating, searching, and sorting arrays, thereby serving as the base class for all arrays in the common language runtime.
  • bool — Boolean value (true or false)
  • Boolean — Same as bool.
  • byte — An 8-bit unsigned integer.
  • Byte — Same as byte.
  • char — A single UTF-8 character.
  • Char — Same as char.
  • Capture — A single successful subexpression capture.
  • Collection<> — A generic collection.
  • Color — Describes a color in terms of alpha, red, green, and blue channels.
  • Colors — A set of predefined colors such as CornFlowerBlue.
  • Convert — Converts a base data type to another base data type.
  • CultureInfo — Information about a specific culture, including the names of the cultere, the writing system, the calendar used, the sort order of strings, and formatting.
  • DateTime — A date and time value.
  • DateTimeKind — Specifies whether a DateTime object represents a local, UTC or unknown time.
  • DateTimeOffset — A point in time, typically expressed as a date and time of day, relative to UTC.
  • DayOfWeek — Specifies the day of the week.
  • decimal — A fixed-precision decimal value.
  • Decimal — Same as decimal.
  • Dictionary<,> — A collection of keys and values.
  • double — A double precision floating-point value.
  • Double — Same as double.
  • Enum — The base class for enumerations.
  • Exception — Errors that occur during application execution.
  • float — A single precision floating-point value (faster but less accurate).
  • Group — The results from a single capturing group.
  • Guid — Represents a globally unique identifier.
  • IConvertible — Defines methods that convert the value of the implementing reference or value type to a common language runtime type that has an equivalent value.
  • ICollection<> — Defines size, enumarators, and synchronization methods for all nongeneric collections.
  • IDictionary<> — A non-generic collection of key/value pairs.
  • IEnumerable<> — Exposes an enumerator, which supports a simple iteration over a non-generic collection.
  • int — A 32-bit signed integer.
  • Int16 — A 16-bit signed integer.
  • Int32 — A 32-bit signed integer.
  • Int64 — A 64-bit signed integer.
  • IList<> — A non-generic collection of objects that can be individually accessed by index.
  • IReadOnlyCollection<> — A strongly-typed, read-only collection of elements.
  • IReadOnlyDictionary<> — A generic read-only collection of key/value pairs.
  • IReadOnlyList<> — A read-only collection of elements that can be accessed by index.
  • KeyValuePair<,> — A key/value pair that can be set or retrieved.
  • List<> — A list of objects that can be accessed by index.
  • long — A 64-bit integer value.
  • Match — Represents the results from a single regular expression match.
  • Math — Provides constants and static methods for common mathematical functions.
  • object — The base class of all .NET class hierarchies.
  • Object — Same as object.
  • Point — an x- and y-coordinate pair in two-dimensional space.
  • Random — A pseudo-random number generator.
  • Regex — An immutable regular expression.
  • RegexOptions — Enumerated values to use to set regular expression options.
  • sbyte — An 8-bit signed integer.
  • SByte — Same as sbyte.
  • short — A 16-bit signed integer.
  • Single — A single-precision floating-point number.
  • string — A character string.
  • String — Same as string.
  • StringComparison — The culture, case, and sort rules to be used by certain overloads of the String.Compare and String.Equals methods.
  • StringSplitOptions — Whether applicable String.Split method overloads include or omit empty substrings from the return value.
  • TimeSpan — Represents a time interval.
  • TimeZoneInfo — The time zone in the world.
  • uint — A 32-bit signed integer.
  • UInt16 — A 16-bit unsigned integer.
  • UInt32 — A 32-bit unsigned integer.
  • UInt64 — A 64-bit unsigned integer.
  • ulong — A 64-bit unsigned integer.
  • ushort — A 16-bit unsigned integer.

You can create new objects using the new keyword for any classes that have been registered with the DundasScript engine.

3. See also

Dundas Data Visualization, Inc.
500-250 Ferrand Drive
Toronto, ON, Canada
M3C 3G8

North America: 1.800.463.1492
International: 1.416.467.5100

Dundas Support Hours: 7am-6pm, ET, Mon-Fri