JS.invoke Function

Format

s = JS.invoke(function_nameʃ, argument1, ..., argumentNʅ);

Description

The JS.invoke function executes a JavaScript function that exists in CSPro's JavaScript global execution context. The function is specified using the string expression function_name, and any CSPro arguments, argument1 to argumentN, are converted to their JavaScript equivalents.

Only some CSPro types have conversion routines. The following table summarizes conversion routines, with the conversion described in detail at the provided links:

CSPro Object	JavaScript Conversion
numeric	Converted to a JavaScript number (or null or string if a special value). Converted from these types, as well as from booleans and single-value arrays.
string / alpha	Converted to a JavaScript string. Converted from a string, number, boolean, or null.
function	Converted to a JavaScript function. It is not possible to convert a JavaScript function to a CSPro function.
Array	Converted to and from a JavaScript array.
HashMap	Converted to and from a JavaScript object.
List	Converted to and from a JavaScript array.

If you are frequently invoking a JavaScript function, consider creating a function wrapper that appears as a CSPro logic user-defined function but calls into JavaScript when invoked.

Return Value

The function returns the JavaScript function's return value as a string, converted using the value's toString method. If the JavaScript evaluation ends in an uncaught exception, the exception's message is displayed as an error message and the function returns a blank string.

Example 1

JS.invoke can execute functions that are part of JavaScript built-in objects, such as static methods in Math.

JS.invoke("Math.max", 2025, 8.1, 25); // 2025
JS.invoke("Math.max", 2025, 8.1, 25, "5000"); // 5000
JS.invoke("Math.max", 2025, 8.1, 25, "five thousand"); // NaN

Example 2

With the following JavaScript script added to the application...

function sumArray(values) {
let sum = 0;
// use forEach to sum the values of an array
values.forEach(value => {
sum += value;
});
return sum;
}

...it is possible to pass Array or List objects due to CSPro to JavaScript conversions:

Array someNumbersArray(4) = 10, 20, 30, 40;
List someNumbersList = 4, 6, 7, 79, 81, 82;

JS.invoke("sumArray", someNumbersArray); // 100
JS.invoke("sumArray", someNumbersList); // 259

Example 3

CSPro logic user-defined functions can be used as arguments. With the following JavaScript script added to the application...

function getCSProVersion(diagnosticsCallback) {
return diagnosticsCallback("version");
}

...it is possible to call into JavaScript and then have JavaScript call back into CSPro.

function string ExecDiagnostics(string property)
exit diagnostics(property);
end;

JS.invoke("getCSProVersion", ExecDiagnostics)); // 8.1
diagnostics("version"); // 8.1