<type> cast( variant value, <type>, <subtype...> );
Version
Miscellaneous functions
List of functions
The rest of the functions can be denominated as miscellaneous. These are the functions listed below.
|
Remember that the object notation (e.g., For more information about object notation, see Functions Reference. |
cast
Returns the value passed as the first argument cast to the type specified as the following arguments.
Returns null if the value is null.
Fails with an error if the value is not of the selected type.
Does not check the type of elements of lists and maps, only checks if the value is a list or map, respectively.
E.g.
the cast of a list of integers to a list of strings does not fail and will lead to runtime errors later in the code, see the examples below.
Use a for loop if you need to check the type of elements.
Compatibility
The cast(variant, type, subtype…) function is available since CloverDX 5.6.0.
Example 303. Usage of cast
variant value = "ABC";
string myString = cast(value, string); // myString contains "ABC"
value = 10;
integer myInteger = cast(value, integer); // myInteger contains 10
date myDate = cast(value, date); // error, "value" currently contains an integer
value = [1, 2, 3];
list[integer] intList = cast(value, list, integer); // intList contains [1, 2, 3]
// does not fail, will lead to runtime exceptions later
list[string] stringList = cast(value, list, string);
// avoid this problem by checking the type of elements before casting to list[string]:
for (integer i = 0; i < length(value); i++) {
variant element = value[i];
// typeof returns false for null
if ((element != null) && !(element typeof string)) {
raiseError(element + " is not a string");
}
}
variant nullVariant = null;
integer nullInteger = cast(nullVariant, integer); // nullInteger contains nullgetCurrentTimeMillis
long currentTimeMillis();The currentTimeMillis() function returns the current time in milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC).
Compatibility
The currentTimeMillis() function is available since CloverDX 6.4.0.
Example 304. Usage of currentTimeMillis()
long millis = currentTimeMillis();
evalExpression
variant evalExpression( string expression );The evalExpression() function evaluates the result of a given expression and returns it as a variant data type. This function is useful for performing dynamic calculations, user-provided expressions, or evaluating conditional statements at runtime.
Potential use cases for the evalExpression function include:
-
Implementing custom business logic or rules using a more human-readable expression syntax.
-
Dynamic calculations based on user input or configuration settings.
-
Parsing and evaluating expressions from external sources, such as files or databases.
Basic syntax for using the function:
string expression = getParamValue("USER_PROVIDED_CONDITION"); // contains: "$in.0.isValid == true"
variant result = evalExpression(expression);
boolean condition = cast(result, boolean);In this example, the expression variable is assigned the value of the USER_PROVIDED_CONDITION graph parameter using the getParamValue function. This demonstrates a use case where the condition to be evaluated is provided dynamically by the user at runtime. In the example user specifies a condition, which checks input field isValid from first input port. The value of expression is then passed to the evalExpression function, which evaluates the expression and returns the result as a variant data type. Please note, if you need to get the actual value with a proper data type, the cast function could be used.
The expression parameter is a string containing the expression to be evaluated. The expression can include arithmetic, logical, or relational operators, as well as functions and constants supported by the CTL engine. The only requirement is the expression should return a value, for, if or other statements are not allowed. In addition to simple expressions, the evalExpression function can handle more complex logic using custom functions.
To reference external custom functions, make sure the function is defined and accessible within the scope of the evalExpression function. The custom function should accept input parameters as needed and return a value that can be used within the expression.
Example 305. Example of using a custom function:
import "trans/myCustomFunctions.ctl";
variant result;
integer a = 4;
integer b = 2;
result = evalExpression("doCalculation(a, b)");
$out.0.output = result; // returns 2.0The external file myCustomFunctions.ctl is:
function number doCalculation(integer a, integer b){
return a/b;
}Error handling
In case the provided expression is invalid or causes a runtime error, the evalExpression function generates an exception. To handle these exceptions, use a try-catch block with the CTLException exception type.
Error handling is important when using the evalExpression function because it is designed for defining external expressions, mainly from users or from dynamic configurations. Therefore, it is necessary to check for syntax and runtime errors. In case the expression is propagated from outside, it is essential to ensure proper error handling to prevent unexpected behavior or crashes in the application.
Example 306. Error handling
import "trans/myCustomFunctions.ctl";
variant result;
integer a = 4;
integer b = 0;
result = evalExpression("doCalculation(a, b)");
$out.0.output = result;The external file myCustomFunctions.ctl is:
function number doCalculation(integer a, integer b){
return a/b;
}In this example, a runtime exception will occur because b is equal to 0, which will cause a division by zero error. The actual source of the exception is in the doCalculation function (which is an external). In this example, the issue occurred on line 7 of the transformation, but the actual error is in myCustomFunctions.ctl on line 2.
Example 307. Error output
Interpreter runtime exception when dynamically evaluating CTL expression on line 12 column 18
----------------------- CTL2 snippet -----------------------
7: result = evalExpression("doCalculation(a, b)");
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------- CTL2 snippet -----------------------
*** Caused by executing CTL code:
Interpreter runtime exception on line 2 column 12 in import trans/myCustomFunctions.ctl
Caused by: java.lang.ArithmeticException -> / by zero
----------------------- CTL2 snippet -----------------------
2: return a/b;Example of error handling with the evalExpression function:
Example 308. Error handling
try {
variant result = evalExpression("user_input");
} catch (const CTLException e) {
printLog(warn, "The input expresssion produces an error. Error details: " + e);
}getEnvironmentVariables
map[string,string] getEnvironmentVariables( );The getEnvironmentVariables() function returns an unmodifiable map of system environment variables.
An environment variable is a system-dependent external named value.
Similar to the Java function System.getenv().
Note that the keys are case-sensitive.
Compatibility
The isEmpty() function is available since CloverETL 3.3.x.
Example 309. Usage of getEnvironmentVariables()
string envPath = getEnvironmentVariables()["PATH"];
See also: getJavaProperties
getJavaProperties
map[string,string] getJavaProperties( );The getJavaProperties() function returns the map of Java VM system properties.
Similar to the Java function System.getProperties().
Compatibility
The getJavaProperties() function is available since CloverETL 3.3.x.
Example 310. Usage of getJavaProperties()
string operatingSystem = getJavaProperties()["os.name"];
See also: getEnvironmentVariables
getParamValue
string getParamValue( string paramName );The getParamValue() function returns the value of the specified graph parameter.
The argument is the name of the graph parameter without the ${ } characters, e.g. PROJECT_DIR.
The returned value is resolved, i.e.
it does not contain any references to other graph parameters.
The function returns null for non-existent parameters.
|
Function |
Compatibility
The getParamValue(string) function is available since CloverETL 3.3.x.
Example 311. Usage of getParamValue
string datainDir = getParamValue("DATAIN_DIR"); // will contain "./data-in"
See also: getParamValues
getParamValues
map[string,string] getParamValues( );The getParamValues() function returns a map of graph parameters and their values.
The keys are the names of the parameters without the ${ } characters, e.g. PROJECT_DIR.
The values are resolved, i.e.
they do not contain any references to other graph parameters.
The map is unmodifiable.
The function returns null for non-existent parameters.
|
The function |
Compatibility
The getParamValues() function is available since CloverETL 3.3.x.
Example 312. Usage of getParamValues
string datainDir = getParamValues()["DATAIN_DIR"]; // will contain "./data-in"
See also: getParamValue
getRawParamValue
string getRawParamValue( string paramName );The getRawParamValue() function returns the value of the specified graph parameter.
The argument is the name of the graph parameter without the ${ } characters, e.g. PROJECT_DIR.
In contrast with getParamValue(string) function, the returned value is unresolved, so references to other graph parameters are not resolved and secure parameters are not decrypted.
The function returns null for non-existent parameters.
Compatibility
The getRawParamValue(string) function is available since CloverETL 3.5.0.
Example 313. Usage of getRawParamValue
string datainDir = getRawParamValue("DATAIN_DIR"); // will contain "${PROJECT}/data-in"
See also: getRawParamValues
getRawParamValues
map[string,string] getRawParamValues( );The getRawParamValues() function returns a map of graph parameters and their values.
The keys are the names of the parameters without the ${ } characters, e.g. PROJECT_DIR.
Unlike getParamValues() function, the values are unresolved, so references to other graph parameters are not resolved and secure parameters are not decrypted.
The map is unmodifiable.
The function returns null for non-existent parameters.
Compatibility
The getRawParamValues() function is available since CloverETL 3.5.0.
Example 314. Usage of getRawParamValues
string datainDir = getRawParamValues()["DATAIN_DIR"]; // will contain "${PROJECT}/data-in"
See also: getRawParamValue
getType
string getType( variant arg );Returns the actual runtime type of the argument as a string.
If the argument is null, the function returns the string "null".
Compatibility
The getType(variant) function is available since CloverDX 5.6.0.
Example 315. Usage of getType
variant myString = "ABC";
string type1 = getType(myString); // "string"
variant myList = ["a", "b", 7];
string type2 = getType(myList); // "list"hashCode
integer hashCode( integer arg );
integer hashCode( long arg );
integer hashCode( number arg );
integer hashCode( decimal arg );
integer hashCode( boolean arg );
integer hashCode( date arg );
integer hashCode( string arg );
integer hashCode( record arg );
integer hashCode( map arg );
integer hashCode( variant arg );Returns java hashCode of parameter.
Compatibility
The hashcode(…) function is available since CloverETL 3.5.0-M1.
Example 316. Usage of hashCode
The function
hashCode(5) returns some number.
iif
<any type> iif( boolean con, <any type>, <any type> );The iif() function returns the second argument if the first argument is true, or the third argument if the first argument is false.
If the first argument is null, the function fails with an error.
Compatibility
The iif(boolean,E,E) function is available since CloverETL 3.0.0.
Example 317. Usage of iif
The function iif(true, "abc", "def") returns abc.
The function iif(false, "abc", "def") returns def.
isnull
boolean isnull( <any type> arg );The isnull() function returns a boolean value depending on whether the argument is null (true) or not (false). The argument may be of any data type.
|
If you set the Null value property in metadata for any For example, if For detailed information, see Null value. |
Compatibility
The isnull() function is available since CloverETL 3.0.0.
Example 318. Usage of isnull
The function isnull(null) returns true.
The function isnull(123) returns false.
nvl
<any type> nvl( <any type> arg, <any type> default );The nvl() function returns the first argument, if its value is not null, otherwise the function returns the second argument.
Both arguments must be of the same type.
Compatibility
The nvl() function is available since CloverETL 3.0.0.
Example 319. Usage of nvl
The function nvl(null, "def") returns def.
The function nvl("abc", "def") returns abc.
nvl2
<any type> nvl2( <any type> arg, <any type>, <any type> );The nvl2() function returns the second argument, if the first argument has not null value.
If the first argument has a null value, the function returns the third argument.
Compatibility
The nvl2(obj,obj,obj) function is available since CloverETL 3.0.0.
Example 320. Usage of nvl2
The function nvl2(null, "abc", "def") returns def.
The function nvl2(123, "abc", "def") returns abc.
getOAuth2Token
string getOAuth2Token( string connectionName );
string getOAuth2Token( string connectionName, boolean forceRefresh );The getOAuth2Token function returns OAuth2 access token from authorized OAuth2 connection linked in graph.
The connectionName parameter is a name of the OAuth2 connection linked in graph.
If the connection specified does not exist or is of the wrong type, an exception is thrown.
The optional parameter forceRefresh can be used to ask the connection to obtain a new OAuth2 access token instead of the currently cached one.
Without forceRefresh parameter, returned tokens are valid for at least the next 60 seconds after the call is made.
Forcing a refresh ensures maximum possible validity time, but it is slower than using default because new tokens must be obtained from remote OAuth2 provider.
Compatibility
The getOAuth2Token(string) function is available since CloverDX 5.12.0.
parseProperties
map[string, string] parseProperties( string properties );The parseProperties() function converts key-value pairs separated with a new line from a string to a map.
The order of properties is preserved.
If the input string is null or empty, the function returns an empty map.
Compatibility
The parseProperties() function is available since CloverETL 4.1.0.
Example 321. Sample property file
# lines starting with # are comments
! The exclamation mark can also mark text as comments.
# This is the simplest property
key = value
# A long property may be separated on multiple lines
longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
# The key and element characters #, !, =, and : are written with
# a preceding backslash to ensure that they are properly loaded.
website = http\://www.cloverdx.com/
# Add spaces to the key
key\ with\ spaces = This is the value that could be looked up with the key "key with spaces".
# Unicode u-umlaut
uuml : \u00FCExample 322. Usage of parseProperties
The function parseProperties("key1=value1\nkey2=value2")["key2"] returns "value2".
Assuming that string variable input contains the sample property file from above, parseProperties(input) produces the following map: {key=value, longvalue=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa,
website=http://www.cloverdx.com/, key with spaces=This is the value that could be looked up with the key "key with spaces"., uuml=ü}.
See also: Properties (as parameter editor type), java.util.Properties.load(Reader), https://en.wikipedia.org/wiki/.properties
printErr
void printErr( <any type> message );The printErr() function prints out the message to the graph execution log with error log level.
This function works as void printErr(<any type> arg, boolean printLocation) with printLocation set to false.
It is a shortcut for printLog(error, message).
Compatibility
The printErr(string) function is available since CloverETL 3.0.0.
The functionality of printErr() has been changed in CloverETL 4.1.
In earlier versions it wrote to the standard error output, which made it difficult to use in CloverDX Server environment.
Example 323. Usage of printErr
The function
printErr("My error message") prints My error message to graph execution log.
void printErr( <any type> message, boolean printLocation );The printErr() function prints out the message and the location of the error (if the second argument is true) to the log with error log level.
Compatibility
The printErr(string,boolean) function is available since CloverETL 3.0.0.
The functionality printErr() has been changed in CloverETL 4.1.
In earlier versions it wrote to the standard error output, which made it difficult to use in CloverDX Server environment.
Example 324. Usage of printErr 2
The function printErr("My error message", true) prints message like My error message (on line: 16 col: 5).
The line number and column number will be different.
The function printErr("My second message", false) prints message My second message.
See also: printLog, raiseError
printLog
void printLog( level loglevel, <any type> message );
void printLog( level loglevel, string logger, <any type> message );The printLog() function sends a message to a logger.
The log level of the message must be one of the following: debug, info, warn, error, or fatal.
The log level must be specified as a constant.
It can be neither be received through an edge nor set as a variable.
By default, the message is logged to a graph’s run log. A custom logger may be chosen by referencing it by the name attribute. If the specified logger doesn’t exist, the function will revert to the default behavior.
For logger Log4j 2 configuration see Logging customization.
Compatibility
The printLog(level,string) function is available since CloverETL 3.0.0.
The printLog(level loglevel, string logger, <any type> message) function is available
since CloverDX 6.4.0.
Example 325. Usage of printLog
The function printLog(warn, "abc") prints abc into the log.
printLog(info, $out.0) prints a string representation of a record to the log.
printLog(error, "myCustomLogger", "Example error message") prints a message to a custom logger.
See also: printErr, raiseError
raiseError
void raiseError( string message );The raiseError() function throws out an error with the message specified as the argument.
The execution of the graph is aborted.
Compatibility
The raiseError(string) function is available since CloverETL 3.0.0.
Example 326. Usage of raiseError
raiseError("The error message")
resolveParams
string resolveParams( string parameter );
string resolveParams( string parameter, boolean resolveSpecialChars );The resolveParams() function substitutes all graph parameters in the parameter by their respective values.
So each occurrence of pattern ${<PARAMETER_NAME>} which is referencing an existing graph parameter is replaced by the parameter’s value.
The function can resolve system properties in a similar manner - e.g. PATH or JAVA_HOME.
You can control what else will be resolved by function parameters:
The argument resolveSpecialChars enables the resolution of special characters (e.g.
\n \u).
If resolveSpecialChars is null, the function fails.
The resolveParams(string) function behaves as string resolveParams(string, false).
|
If you are passing the it is automatically resolved. The code above will print an asterisk, even if you omit the second line. It is because resolving is triggered when processing the quotes which surround the parameter. |
Compatibility
The nvl2(obj,obj,obj) function is available since CloverETL 3.3.x.
Example 327. Usage of resolveParams
If you type "DATAIN_DIR is ${DATAIN_DIR}", the parameter is resolved and the usage of the function resolveParams() is not necessary.
The usage of the function resolveParams() is necessary if the string containing a parameter is created at runtime:
string parameter = "DATAIN_DIR";
string substituted = 'data in is ${' + parameter + '}';
string result = resolveParams(substituted);The escape sequences are converted to particular characters: "ls \u002A." is converted to "ls *".
When the escape sequence is created on the fly, the usage of the function resolveParams() is necessary to create a corresponding character:
string special = "\\u" + "002A"; // Unicode for asterisk - *
string result = resolveParams(special, true, false);
printErr(result);sleep
void sleep( long duration );The sleep() function pauses the execution for specified time in milliseconds.
Compatibility
The sleep(long) function is available since CloverETL 3.1.0.
Example 328. Usage of sleep
The function
sleep(5000) will sleep for 5 seconds.
toAbsolutePath
string toAbsolutePath( string path );The toAbsolutePath() function converts the specified path to an OS-dependent absolute path to the same file.
The input may be a path or a URL.
If the input path is relative, it is resolved against the context URL of the running graph.
If running on the Server, the function can also handle sandbox URLs. However, a sandbox URL can only be converted to an absolute path, if the file is locally available on the current server node.
If the conversion fails, the function returns null.
If the given parameter is null, the function fails with an error.
|
The returned path will always use forward slashes as directory separator, even on Microsoft Windows systems. If you need the path to contain backslashes, use the |
Compatibility
The toAbsolutePath(string) function is available since CloverETL 3.3.x.
Example 329. Usage of toAbsolutePath
The function
toAbsolutePath("graph") will return for example C:/workspace/doc_project/graph.
See also: translate