JS.getValue Function

Format

b = JS.getValue(name, out_value);

Description

The JS.getValue function converts a JavaScript variable or property to a CSPro logic variable or object identified as out_value. This is a useful way to transfer data from JavaScript to CSPro logic when a conversion routine exists. Another way to transfer data is using JSON with the JS.getValueJson function.

The string expression name is evaluated and can refer to a variable in CSPro's JavaScript global execution context or an object's property if the object exists globally. For example, the following values can be specified as a name:

myFunction
globalThis.myFunction
myObject.myProperty
myObject['my' + 'Property']

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.

Note that function objects cannot be converted from JavaScript. All of the types can be converted to JavaScript by using the JS.setValue function.

Return Value

The function returns a logical value of 1 (true) if the CSPro variable or object is successfully set. If the JavaScript variable or property is undefined, the function returns 0 (false) and displays an error message. If you do not want to see the error message, check the existence of the variable or property by using the JS.hasValue function. If JavaScript evaluation ends in an uncaught exception, the function also returns false. On error, the destination CSPro variable or object is not modified.

Example

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

function createRandomNumbers(count) {
return Array.from({ length: count }, () => Math.random());
}

...it is possible to get the result of the function as a CSPro List.

// we must use var, not let or const, because JS.getValue works with variables in the global object
JS.eval("var randomNumbersJS = createRandomNumbers(5);");

List randomNumbersCS;
JS.getValue("randomNumbersJS", randomNumbersCS);

// displays text similar to: 5 random values created in JavaScript: 0.107350 ... 0.373519
errmsg("%d random values created in JavaScript: %f ... %f",
randomNumbersCS.length(),
randomNumbersCS(1),
randomNumbersCS(randomNumbersCS.length()));