AddVariableEx

Adds a user-defined variable to a specified folder.

Syntax

KsError AddVariableEx(
     UserVariable* Variable,
     HANDLE Parent
);

Parameters

Variable: the variable you want to add. See the UserVariable structure.

Parent: the parent folder of UserVariable. Input NULL if you want to add variables to the root folder. Use AddVariableEx(&VAR1, DIR.Id) if you want to add variables to a specific folder.

Return value

If the function succeeds, it returns errNoError, otherwise an error code. For more information about the error code, see the KsError list.

Remarks

• The variable can be used in KINGSTAR Scope and a real-time log.
• When using logDirectory to create a directory, you can further configure the folder size with UserVariable, for example:

  UserVariable dir = { nullptr, L"DIR0", IntToPtr(128),

  KsLogDataType::logDirectory }

  • When Parent is set as NULL, the UserVariable will be added to the default directory, which is the root folder. In such case, the space of the root folder can store up to 64 UserVariable and cannot be changed.
  • When Parent is not set as NULL, the UserVariable will be added to the specified directory. In such case, you can configure the folder size of the directory.
    • Folder size = 0, the space of the directory will be applied with the default value, which can store up to 64 UserVariable.
    • Folder size ≠ 0, the space of the directory will be applied with the specified value.

Usable EtherCAT states

ecatOffline, ecatInit, ecatBoot, ecatPreOP, ecatSafeOP, ecatOP

Example

    // Create directory
    UserVariable dir0 = { 0 };
    int size = 128;

    dir0.Type = KsLogDataType::logDirectory;
    dir0.Value = IntToPtr(size);
    swprintf_s(dir0.Name, L"DIR%d", 0);

    auto errorId = AddVariableEx(&dir0, nullptr);
    if (errorId != KsError::errNoError)
        RtPrintf("[ERROR] Create directory.0, ErrorId: 0x%x\n", errorId);

    // Add variable to directory
    std::vector<UserVariable> addedVars = std::vector<UserVariable>(size, { 0 });

    for (int i = 0; i < size; ++i)
    {
        addedVars[i].Type = KsLogDataType::logDouble;
        swprintf_s(addedVars[i].Name, L"VAR%d", i);

        errorId = AddVariableEx(&addedVars[i], dir0.Id);
        if (errorId != KsError::errNoError)
            RtPrintf("[ERROR] Add variable.%d, ErrorId: 0x%x\n", i, errorId);
    }

Requirements

See also

AddVariable

GetVariable

GetVariableEx

GetVariables

GetVariablesEx

RemoveVariable