DTM scripts are written in Visual Basic.Net. A given script is run after having established a current source row (“object”). The goal of the script is to determine a single value – the “result” value – and assign that value to the keyword DTM.Result. For different types of scripts, the script result represents different things.
Transform scripts: the script result is the value of a destination field.
Container scripts: the script result is the distinguished name of a parent container.
DTM keywords
DTM keywords give you access to the data being transformed.
DTM.Source(<fieldname>)
This is function with a single string argument: field name. DTM.Source returns the value of the specified field (or “attribute”) for the current row (“object”) in the source data.
DTM.Result
This is a write-only property. DTM.Result must be assigned a value by the script. What the value signifies depends upon the type of script.
Transform script – assign to DTM.Result the desired value of the transform’s destination field.
Container script – assign to DTM.Result the distinguished name of the new object’s container.
In any script, each branch of execution of the script must assign a value to DTM.Result. Failure to assign a value to DTM.Result will cause a runtime error, and the destination row (“object”) will be not be updated/created. The job will still run to completion.
DTM.ExpandVariables(<text>)
This is function with a single string argument: text. Returns the value, as a string, of the specified text after replacing each environment variable embedded in the text with the string equivalent of the value of the variable. Environment variables are surrounded by “%” characters, as in: “%now%”, “%SystemDrive%”, etc.
DTM.CancelRow()
This is a subroutine with no arguments. The current destination row (“object”) will not be updated/created. DTM.CancelRow provides a way to bypass certain objects based on their attributes. (In general, for performance reasons, it is preferable to use a filter query for this purpose).
Scripting Restrictions Enforced By DTM
Behind the scenes, DTM inserts each script into the body of a subroutine before compiling. Therefore, any Visual Basic.Net constructs that are only valid outside of a subroutine/function will fail to compile and will be disallowed.
When creating a DTM script, the following restrictions apply:
Subroutines, functions, classes, modules, namespaces are not allowed.
Module-level statements, such as Import or Option statements, are not permitted.
Shared (i.e., static, global) variables are not supported.
VB Options Set By DTM
DTM establishes the following Option statements. These options apply to all scripts and cannot be overridden:
Option Explicit On – all variables must be declared before use via a Dim statement. With VB.Net, it is possible to both declare and assign variables at their first use, as in:
Dim MyVariable = “Hello”
Dim MyObject = new Object()
Option Strict Off – datatypes don’t need to be declared for each variable. Conversions between types, when possible, are performed implicitly. (By declaring datatypes, unnecessary conversions can be avoided, and performance improved).
.Net Assembly References
DTM establishes certain system assembly references before compiling your scripts. These references apply to all scripts and cannot be overridden. These references are:
MsCorLib.dll
System.dll
System.Data.dll
System.Xml.dll
System.DirectoryServices, in particular, is “off-limits” to your scripts. This prevents direct access to ActiveDirectory and other LDAP data stores. This is a desirable restriction, as it prevents your script from acting in conflict with DTM – which, after all, has final responsibility for updating these data stores.
.Net Namespaces
DTM imports certain namespaces when compiling your scripts. These imports apply to all scripts and cannot be overridden. These imports are:
Imports System
Imports System.Text
Imports System.Text.RegularExpressions
Imports System.IO
Imports System.Math
.Net namespaces other than those listed here can still be accessed by specifying the fully-qualified namespace. For example, a DataSet (which belongs to the System.Data namespace) can be read from a file as follows:
Dim ds = New System.Data.DataSet()
ds.ReadXml(“C:\Temp\MyFile.xml”)