Class WinccoaCtrlScript

Class that represents a CTRL script that can be called from JavaScript/TypeScript. The necessary steps to call a CTRL function are:

  1. Create an instance of WinccoaCtrlScript.
  2. Call a function in the script with start.

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

import {
WinccoaCtrlScript,
WinccoaCtrlType,
WinccoaManager,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();

async function ctrlScriptExample() {
// create instance of script with CTRL code to execute
const script = new WinccoaCtrlScript(
winccoa,
`dyn_string main(string pattern, bool empty = true)
{
return dpTypes(pattern, getSystemId(), empty);
}`
);

try {
// call the script with two parameters
let types = await script.start(
'main',
['Ex*', false],
[WinccoaCtrlType.string, WinccoaCtrlType.bool]
);

// show result
console.warn(types);
} catch (exc) {
console.error(exc);
}
}

Constructors

Properties

Methods

Constructors

  • 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.

    Parameters

    • manager: WinccoaManager

      Manager instance that is used for getting the user ID and options to use for the subsequent call of start

    • ctrlCode: string

      CTRL code for the script. Must contain a CTRL function.

    Returns WinccoaCtrlScript

    Throws

    WinccoaError when manager is not the correct type or ctrlCode contains a syntax error.

    See

    WinccoaOptions

Properties

script: CtrlScript

Methods

  • Calls a CTRL function in the script set with the constructor. Can only be called once. For an example, see WinccoaCtrlScript.

    Parameters

    • functionName: string = 'main'

      Name of the CTRL function to call.

    • functionParams: unknown[] = []

      Parameters for the CTRL function.

    • paramTypes: unknown[] | WinccoaCtrlType[] = []

      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.

    Returns Promise<unknown>

    Promise for the return value. Resolved when the function returns or rejected when the script is stopped (see stop).

    Throws

    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.

    See

    WinccoaCtrlType

    Example

    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]
    );

    Example

    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]
    );

    Example

    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]
    );

    Example

    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 }]
    );

    Example

    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).

    Returns void

    Example

    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
    }