readSymbol

[ Function ]

Version 1.8

public static readSymbol(
    symbolName: string | string[], 
    callback?: null | (
         (data: TcHmi.Server.IResultObject) => void
    )
): number | null;

Version 1.12

public static readSymbol<W = any, R = any>(
    symbolName: string | string[], 
    callback?: null | (
         (data: TcHmi.Server.IResultObject<W, R>) => void
    )
): number | null;

Reads one or more values from a TwinCAT HMI server symbol.

Version 1.12

If the API is used in TypeScript code, the TypeScript compiler can be notified of the server symbol type. A later access to readValue in the callback function then automatically has the correct type. Here, the type of the value is specified first when writing (Write) and then optionally the type of the value to be read (Read).

When accessing several symbols with different types, the type can be manually set to any.

This is a merely an auxiliary programming feature. The browser does not recognize this "type annotation". No check or conversion takes place at runtime.

Parameter

Return value

Available from 1.8

Sample - JavaScript

// Read single symbol
TcHmi.Server.readSymbol('PLC1.MAIN.bTest', function(data){
    if(data.error !== TcHmi.Errors.NONE){
        // Handle TcHmi.Server class level error here.
        return;
    }
    var response = data.response;
    if (!response || response.error !== undefined) {
        // Handle TwinCAT HMI Server response level error here.
        return;
    }
    var commands = response.commands;
    if(commands === undefined){
        return;
    }
    var command = commands[0];
    if(command === undefined){
        return;
    }
    if(command.error !== undefined){
        // Handle TwinCAT HMI Server command level error here.
        return;
    }
    // Handle result...
    TcHmi.Log.debugEx('PLC1.MAIN.bTest:', command.readValue); // Editor does not know the value type
});

// Read multiple symbols
TcHmi.Server.readSymbol(['PLC1.MAIN.bTest', 'PLC1.MAIN.iTest'], function(data){
    if(data.error !== TcHmi.Errors.NONE){
        // Handle TcHmi.Server class level error here.
        return;
    }
    var response = data.response;
    if (!response || response.error !== undefined) {
        // Handle TwinCAT HMI Server response level error here.
        return;
    }
    var commands = response.commands;
    if(commands === undefined){
        return;
    }
    var command = commands[0];
    if(command === undefined){
        return;
    }
    if(command.error !== undefined){
        // Handle TwinCAT HMI Server command level error here.
        return;
    }
    // Handle result...
    TcHmi.Log.debugEx('PLC1.MAIN.bTest:', command.readValue); // Editor does not know the value type

    var command1 = commands[1];
    if(command1 === undefined){
        return;
    }
    if(command1.error !== undefined){
        // Handle TwinCAT HMI Server command level error here.
        return;
    }
    // Handle result...
    TcHmi.Log.debugEx('PLC1.MAIN.iTest:', command1.readValue); // Editor does not know the value type
});

Sample - TypeScript

// Read single symbol with type annotation
TcHmi.Server.readSymbol<string>('PLC1.MAIN.bTest', function(data){
    if(data.error !== TcHmi.Errors.NONE){
        // Handle TcHmi.Server class level error here.
        return;
    }
    var response = data.response;
    if (!response || response.error !== undefined) {
        // Handle TwinCAT HMI Server response level error here.
        return;
    }
    var commands = response.commands;
    if(commands === undefined){
        return;
    }
    var command = commands[0];
    if(command === undefined){
        return;
    }
    if(command.error !== undefined){
        // Handle TwinCAT HMI Server command level error here.
        return;
    }
    // Handle result...
    TcHmi.Log.debugEx('PLC1.MAIN.bTest:', command.readValue); // Editor knows this is a string
});