JS.setValue Function

Format

b = JS.setValue(name, value);

Description

The JS.setValue function sets the value of a JavaScript variable or property from a CSPro logic variable or object identified as value. This is a useful way to transfer data from CSPro logic to JavaScript when a conversion routine exists. This function can be used to create new variables or properties, or to modify existing ones. Another way to transfer data is using JSON with the JS.setValueFromJson 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.

All of the types, with the exception of function, can be converted from JavaScript by using the JS.getValue function.

Return Value

The function returns a logical value of 1 (true) if the JavaScript variable or property is successfully set. If JavaScript evaluation ends in an uncaught exception, the function returns 0 (false) and displays an error message.

Example

// create a JavaScript array using a CSPro List
List numeric primeNumbers = 2, 3, 5, 7, 11, 13, 17, 19, 23;
JS.setValue("primes", primeNumbers);

// add to the array, setting the array's property, using a CSPro numeric expression
JS.setValue("primes[9]", 29);

// create a JavaScript string from a CSPro string expression
JS.setValue("primeMessagePrefix",
maketext("This is an operation using values from CSPro %s:", diagnostics("version")));

// displays: This is an operation using values from CSPro 8.1: The sum of the first 10 prime values is 129!
errmsg("%s", JS.eval("`${primeMessagePrefix} "
"The sum of the first ${primes.length} prime values "
"is ${primes.reduce((a, b) => a + b)}!`"));