Constructor. Creates an instance and initializes it with the CTRL code that will be executed. The script must then be started with a call to start. This also sets the user ID for the subsequent call of 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 a CTRL function.
WinccoaError when manager
is not the correct type or ctrlCode
contains a syntax error.
WinccoaOptions
Private
managerPrivate
scriptCalls a CTRL function in the script set with the constructor. Can only be called once. 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.
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 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);
let result = await script.start(
'simpleArgs',
[12, 34.56, 'some text'],
[WinccoaCtrlType.int, WinccoaCtrlType.double, WinccoaCtrlType.string]
);
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);
let result = await script.start(
'dynArg',
[['can', 'this', 'thing', 'be', 'found', 'in', 'here']],
[WinccoaCtrlType.dyn_string]
);
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);
let result = await script.start(
'dynAnytypeArg',
[['title', 4711], false],
[[WinccoaCtrlType.string, WinccoaCtrlType.int], WinccoaCtrlType.bool]
);
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);
let 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);
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 },
],
],
]
);
Stops the script if it is still running.
For stopping a running script, the call to stop must come
from a different part of the code than the await
start.
(e.g. from a setTimeout
callback).
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 script after 2 seconds
setTimeout(() => script.stop(), 2000);
try {
result = await script.start('count', [500], [WinccoaCtrlType.int]);
} 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:
Note that start can only be called once on each instance of WinccoaCtrlScript. The separation into a constructor and a start method is necessary to allow stopping a running script by calling stop on the script object.
Example