Miscellaneous Functions

	Important
Remember that the object notation (e.g., `arg.isnull()`) cannot be used for these Miscellaneous functions. For more information about object notation, see Chapter 69, Functions Reference.

cast

<type> cast(variant value, <type>, <subtype...>);

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 69.231. 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 null

See also: variant, getType, typeof

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 69.232. 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 69.233. 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.

	Note
	Function `getParamValue` decrypts secure parameters.

Compatibility

The getParamValue(string) function is available since CloverETL 3.3.x.

Example 69.234. 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.

	Note
	The function `getParamValues` decrypts secure parameters.

Compatibility

The getParamValues() function is available since CloverETL 3.3.x.

Example 69.235. 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 69.236. 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 69.237. 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 69.238. Usage of getType

variant myString = "ABC";
string type1 = getType(myString); // "string"
variant myList = ["a", "b", 7];
string type2 = getType(myList); // "list"

See also: variant, cast, typeof

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 69.239. Usage of hashCode

The function hashCode(5) returns some number.

iif

<any type> iif(boolean con, <any type> iftruevalue, <any type> iffalsevalue);

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 69.240. Usage of iif

The function iif(true, "abc", "def") returns abc.

The function iif(false, "abc", "def") returns def.

See also: nvl, nvl2

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.

Important

	Important
If you set the Null value property in metadata for any `string` data field to any non-empty string, the `isnull()` function will return `true` when applied on such string. And return `false` when applied on an empty field. For example, if `field1` has Null value property set to `"<null>"`, `isnull($in.0.field1)` will return `true` on the records in which the value of `field1` is `"<null>"` and `false` on the others, even on those that are empty. For detailed information, see Null value.

If you set the Null value property in metadata for any string data field to any non-empty string, the isnull() function will return true when applied on such string. And return false when applied on an empty field.

For example, if field1 has Null value property set to "<null>", isnull($in.0.field1) will return true on the records in which the value of field1 is "<null>" and false on the others, even on those that are empty.

For detailed information, see Null value.

Compatibility

The isnull() function is available since CloverETL 3.0.0.

Example 69.241. Usage of isnull

The function isnull(null) returns true.

The function isnull(123) returns false.

See also: isNull, nvl, nvl2

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 69.242. Usage of nvl

The function nvl(null, "def") returns def.

The function nvl("abc", "def") returns abc.

See also: iif, isnull, nvl2

nvl2

<any type> nvl2(<any type> arg, <any type> arg_for_non_null, <any type> arg_for_null);

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 69.243. Usage of nvl2

The function nvl2(null, "abc", "def") returns def.

The function nvl2(123, "abc", "def") returns abc.

See also: iif, isnull, nvl

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 69.244. 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 : \u00FC

Example 69.245. 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 69.246. 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 69.247. 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);

The printLog() function sends out the message to a logger.

The log level of the message is one of the following: debug, info, warn, error, fatal. The log level must be specified as a constant. It can be neither received through an edge nor set as variable.

	Note
	Remember that you should use this function especially in any graph that would run on CloverDX Server instead of the `printErr()` function which logs error messages to the log of the Server (e.g. to the log of Tomcat). Unlike `printErr()`, `printLog()` logs error messages to the console even when the graph runs on CloverDX Server.

Compatibility

The printLog(level,string) function is available since CloverETL 3.0.0.

Example 69.248. Usage of printLog

The function printLog(warn, "abc") prints abc into the log.

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 69.249. Usage of raiseError

raiseError("The error message")

See also: printErr, printLog

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

Note

If you are passing the parameter directly, not as a metadata field, e.g. like this:

string special = "\u002A"; // Unicode for asterisk - *
resolveParams(special, true); // this line is not needed
printErr(special);

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 69.250. 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 69.251. 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.

Note

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 translate()function:

string absolutePath = toAbsolutePath(path).translate('/', '\\');

Compatibility

The toAbsolutePath(string) function is available since CloverETL 3.3.x.

Example 69.252. Usage of toAbsolutePath

The function toAbsolutePath("graph") will return for example C:/workspace/doc_project/graph.

See also: translate

List of functions

cast

getEnvironmentVariables

getJavaProperties

getParamValue

getParamValues

getRawParamValue

getRawParamValues

getType

hashCode

iif

isnull

nvl

nvl2

parseProperties

printErr

printLog

raiseError

resolveParams

sleep

toAbsolutePath