Constructor. Creates an instance and initializes it with the CTRL code that will be executed. A function in the script must then be started with a call to start. For an example, see WinccoaCtrlScript.
Manager instance that is used for getting the user ID and options to use for the subsequent call of start
CTRL code for the script. Must contain at least one CTRL function.
Optionalname: stringOptional name for the script that will be shown in error messages.
Optionalcallback: WinccoaCtrlCallbackIf given, this function can be called from the CTRL script
by using the CTRL function callbackToJavaScript(). See
WinccoaCtrlCallback for details and examples.
WinccoaError when manager is not the correct type or ctrlCode
contains a syntax error.
ReadonlyctrlCTRL code for the script. Must contain at least one CTRL function.
Optional ReadonlynameOptional name for the script that will be shown in error messages.
Calls a CTRL function in the script set with the constructor. For each call, a new CTRL thread is created. For an example, see WinccoaCtrlScript.
Name of the CTRL function to call.
Parameters for the CTRL function.
Types of the parameters as expected by the CTRL function. Note that in this context, it is not possible to determine the required parameter types automatically, therefore it is necessary to specify them explicitely.
For CTRL types that can contain different types (e.g. anytype, mixed, mapping), the concrete types to which the values have to be converted before they are passed to CTRL have to be provided.
For dynamic arrays containing a single datatype, it is recommended and more efficient to use the specific type, e.g. WinccoaCtrlType.dyn_float.
Optionalcallback: WinccoaCtrlCallbackIf given, this function can be called from the CTRL script
by using the CTRL function callbackToJavaScript(). See
WinccoaCtrlCallback for details and examples.
NOTE
In general, it is preferable to use the callback parameter of WinccoaCtrlScript.constructor instead of this parameter.
While this parameter here allows you to have different callback functions when start is called more than once, this callback will only work when
callbackToJavaScript()is called in the CTRL thread that has been created by the corresponding call to start. In particular, callingcallbackToJavaScript()in a CTRL callback function (e.g. fromdpConnect()) will only work when the callback parameter of WinccoaCtrlScript.constructor is used, but not with this function.
Promise for the return value. Resolved when the function returns or rejected when the script is stopped (see stop).
WinccoaError when parameters cannot be properly converted or when a severe error happened in the script (which also stops the execution of the script). Note that CTRL warnings are only logged, but do not stop the execution of a script.
import {
WinccoaCtrlScript,
WinccoaCtrlType,
WinccoaManager,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
// for a simple argument list, just list the argument types
const ctrlCode = `double simpleArgs(int x, double y, string s)
{
return (x * y) + s.length();
}`;
const script = new WinccoaCtrlScript(winccoa, ctrlCode, 'simple argument');
const result = await script.start(
'simpleArgs',
[12, 34.56, 'some text'],
[WinccoaCtrlType.int, WinccoaCtrlType.double, WinccoaCtrlType.string]
) as number;
import {
WinccoaCtrlScript,
WinccoaCtrlType,
WinccoaManager,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
// for a dynamic array with a fixed type, use the corresponding type.
const ctrlCode = `int dynArg(dyn_string strings)
{
for (int i = 0; i < strings.count(); i++)
if (strings.at(i) == "found")
return i;
return -1;
}`;
const script = new WinccoaCtrlScript(winccoa, ctrlCode, 'dynamic arrays');
const result = await script.start(
'dynArg',
[['can', 'this', 'thing', 'be', 'found', 'in', 'here']],
[WinccoaCtrlType.dyn_string]
) as number;
import {
WinccoaCtrlScript,
WinccoaCtrlType,
WinccoaManager,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
// for a dyn_anytype or dyn_mixed, list the types of all items
const ctrlCode = `string dynAnytypeArg(dyn_anytype things, bool other)
{
if (!ignore)
return "[" + things.count() + "] " + things;
else
return "";
}`;
const script = new WinccoaCtrlScript(winccoa, ctrlCode, 'dynamic arrays, variable types');
const result = await script.start(
'dynAnytypeArg',
[['title', 4711], false],
[[WinccoaCtrlType.string, WinccoaCtrlType.int], WinccoaCtrlType.bool]
) as string;
import {
WinccoaCtrlScript,
WinccoaCtrlType,
WinccoaManager,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
// for a mapping, list the types of all fields
const ctrlCode = `mapping mappingArg(mapping values)
{
values["square"] = values["a"] * values["a"];
values["result"] = values["title"] + ": " + values["square"];
return values;
}`;
const script = new WinccoaCtrlScript(winccoa, ctrlCode, 'mapping arguments');
const result = await script.start(
'mappingArg',
[{ title: 'This is the square', a: 3.01 }],
[{ title: WinccoaCtrlType.string, a: WinccoaCtrlType.float }]
);
import {
WinccoaCtrlScript,
WinccoaCtrlType,
WinccoaManager,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
// for nested arguments, repeat the structure of the arguments,
replacing the values with their types
const ctrlCode = `void nestedArg(dyn_anytype things)
{
DebugTN(things);
}`;
const script = new WinccoaCtrlScript(winccoa, ctrlCode, 'nested arguments');
await script.start(
'nestedArg',
[
[
[1, 2, 3],
{ a: 4.3, b: 'text' },
['something', 12.34, { yes: true, no: false }],
],
],
[
[
WinccoaCtrlType.dyn_int,
{ a: WinccoaCtrlType.float, b: WinccoaCtrlType.string },
[
WinccoaCtrlType.string,
WinccoaCtrlType.float,
{ yes: WinccoaCtrlType.bool, no: WinccoaCtrlType.bool },
],
],
]
);
import {
WinccoaManager,
WinccoaCtrlScript,
WinccoaCtrlType,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
async function parallelCtrlThreads() {
const script = new WinccoaCtrlScript(
winccoa,
`int countMilliSeconds(int count, int delayMs)
{
for (int i = 1; i <= count; i++)
delay(0, delayMs);
return count * delayMs;
}
int countSeconds(int count, int delaySec)
{
for (int i = 1; i <= count; i++)
delay(delaySec);
return count * delaySec * 1000;
}`,
'parallel CTRL threads'
);
// start three parallel CTRL threads and collect all results
const result = await Promise.allSettled([
script.start(
'countMilliSeconds',
[10, 250],
[WinccoaCtrlType.int, WinccoaCtrlType.int],
),
script.start(
'countSeconds',
[5, 1],
[WinccoaCtrlType.int, WinccoaCtrlType.int],
),
script.start(
'countSeconds',
[3, 2],
[WinccoaCtrlType.int, WinccoaCtrlType.int],
),
]);
console.info(result);
}
Stops all threads currently running in this instance.
For stopping running threads, the call to stop must come
from a different part of the code than the await start.
(e.g. from a setTimeout callback). An alternative to that is
to use start without await and handle the Promise later
(e. g. with Promise.allSettled());
import {
WinccoaCtrlScript,
WinccoaCtrlType,
WinccoaManager,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
const ctrlScript = `int count(int tenths)
{
int i;
for(i = 1; i <= tenths; i++)
delay(0, 100);
return i - 1;
}`;
const script = new WinccoaCtrlScript(winccoa, ctrlScript, 'stop example');
// stop script after 2 seconds
setTimeout(() => script.stop(), 2000);
try {
result = await script.start('count', [500], [WinccoaCtrlType.int]) as number;
} catch (exc) {
// interrupted
}
Class that represents a CTRL script that can be called from JavaScript/TypeScript. The necessary steps to call a CTRL function are:
Example