Home | Table of Contents | Miscellaneous Functions | CloverETL 4.6.1
--- | --- | ---
Prev | Functions Reference | Next

## Miscellaneous Functions

###### List of functions

getEnvironmentVariables | nvl
getJavaProperties | nvl2
getParamValue | parseProperties
getParamValues | printErr
getRawParamValue | printLog
getRawParamValues | raiseError
hashCode | resolveParams
iif | sleep
isnull | toAbsolutePath

The rest of the functions can be denominated as miscellaneous. They are the functions listed below.

| 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 61, Functions Reference.

### 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 Java the function `System.getenv()`. Note that the keys are case-sensitive.

Example 61.221. 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 Java the function `System.getProperties()`.

Example 61.222. 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 doesn't contain any references to other graph parameters.

The function returns `null` for non-existent parameters.

| Note
Function `getParamValue` decrypts secure parameters.

Example 61.223. 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 don't 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.

Example 61.224. 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 de-crypted.

The function returns `null` for non-existent parameters.

Example 61.225. 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 de-crypted. The map is unmodifiable.

The function returns `null` for non-existent parameters.

Example 61.226. Usage of getRawParamValues

`string datainDir = getRawParamValues()["DATAIN_DIR"]; // will contain "${PROJECT}/data-in"`

See also: getRawParamValue

### 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`)`;

Returns java hashCode of parameter.

Example 61.227. 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 if the first is `false`.

If the first argument is `null`, the function fails with error.

Example 61.228. 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
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. See Null value for detailed information.

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

Example 61.230. 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 `null` value, the function returns the third argument.

Example 61.231. 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 notice: The function `parseProperties()` is available since CloverETL 4.1.0.

Example 61.232. 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.cloveretl.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 61.233. 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.cloveretl.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 notice: The functionality `printErr()` has been changed in CloverETL version `4.1`. In earlier versions it wrote to the standard error output, which made it difficult to use in CloverETL Server environment.

Example 61.234. 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 notice: The functionality `printErr()` has been changed in CloverETL version `4.1`. In earlier versions it wrote to the standard error output, which made it difficult to use in CloverETL Server environment.

Example 61.235. 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 color 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 CloverETL Server instead of the `printErr()` function which logs error messages to the log of Server (e.g., to the log of Tomcat). Unlike `printErr()`, `printLog()` logs error messages to the console even when the graph runs on CloverETL Server.

Example 61.236. 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 error with the `message` specified as the argument.

The execution of the graph is aborted.

Example 61.237. 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`, 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.

Example 61.238. 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);

See also: getEnvironmentVariables, getJavaProperties, getParamValues, getParamValue, Chapter 36, Parameters

### sleep

`void sleep(`long duration`)`;

The `sleep()` function pauses the execution for specified milliseconds.

Example 61.239. 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 a given parameter is `null`, the function fails with 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('/', '\\');

Example 61.240. Usage of toAbsolutePath

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

Prev | Up | Next
Record Functions (dynamic field access) | Home | Table of Contents | Lookup Table Functions