VarTools

Version Information

This documentation is for version 0.11.2 of the VarTools library.

Description

Helper library for getting and setting variable values. To use the functions within this library the variables must be declared in a .var file as opposed to inline.

Library Specific Structures

VarVariable_typ

VAR_TYPE_enum

VAR_ERR_enum

Functions

varGetInfo

The function varGetInfo() is used to complete the varVariable-typ structure for a given process variable. The variable must have either name or address AND dataType filled out or the function will not work. If the address is 0 and the name is not specified the function will be called in an infinite loop. Please note this function will change the input structure

Parameters

Example

testVariable := 27;

varVariable.name := 'myTask:testVariable';
pVarVariable := ADR(varVariable);

status :=  varGetInfo( pVarVariable );
//varVariable.name = 'myTask:testVariable'
// varVariable.value = '27'
// varVariable.address = 
// varVariable.dataType = 3
// varVariable.length = 2
// varVariable.dimension = 1 look it up

After the function call, the varVariable structure will be completely filled out and status will be 0.

Example

varVariable.address = 0;
pVarVariable := ADR(varVariable);
// varVariable.address = 0
// varVariable.dataType = Undefined

After the function call, the function will be called repeatedly and will return status of 0.

varGetValue

The function VarGetValue() is used to get the value within a process variable and sets the value property in the structure as a string. If address in pVarVariable is 0 the function will call varGetInfo(). varGetValue() takes one pointer to a varVariable_typ and sets the value member and returns 0 on successful completion.

Parameters

fix input name

Example

find the function that gets task name and use it in an example

St_name();

show this somewhere else

testVariable := 27;

varVariable.name := 'myTask:testVariable';
pVarVariable := ADR(varVariable);

status :=  varGetValue( pVarVariable );
//varVariable.name = 'myTask:testVariable'
// varVariable.value = '27'

After the function call, the varVariable structure will have a value of type string filled into varVariable.value and status will equal 0.

varGetRealValue

The function varGetRealValue() is used to get the value property of the varVariable_typ structure as a REAL. This function takes two inputs the first is a pointer to the varVariable_typ structure with the REAL value as a string, the second is pointer to the REAL variable converted string will be stored. If there is no address assigned to the varVariable_typ structure the function will first call varGetInfo() before proceeding to further steps.

Parameters

Example

value := 0;
pValue := ADR(value);
varVariable.value := '23777567';
pVarVariable := ADR(varVariable);

varGetRealValue(pVarVairable, pValue);

After the function call, value will be have 23777567 varVariable.value will be untouched and return 0 on successful completion of function.

varSetValue

The function varSetValue() is used to set the value of a process variable from the value property of a varVariable_typ structure. This function takes one variable that contains a pointer to the varVariable_typ structure. If there is no address assigned to the varVariable_typ structure the function will first call varGetInfo() before proceeding to further steps.

Parameters

Example

testVar := 0;
varVariable.name := 'myTask:testVar';
varVariable.value := '909';
pVarVariable := ADR(varVariable);

status := varSetValue(pVarVariable);

After the function call, varVariable.value will remain unchanged, testVar will be 909 status will be 0.

varGetVariableList

The function varGetVariableList() is used to get a list of all local and global variables with a given name specified in pVariableName. This function takes two inputs. The first is a pointer to a STRING and the second is a pointer to a string array. The list will be returned in alphabetical order. Capitalization will matter for searching purposes. Please note global variables must start with a ‘g’ to be found.

Parameters

Example

variableName := 'Configuration';
pList := ADR(list);

numVarFound := varGetVariableList( &variableName , pList);
//list[0] := 'myTask:Configuration';
//list[1] := 'gConfiguration';

After the function call, varVariable will be unchanged, list will contain strings of all local and global variables matching ‘Configuration’ and numVarFound will be 2;

varVariableWatch

The function block varVariableWatch() is used to monitor a variable’s value property. The main difference between this function block and varGetValue is that it will monitor the name property for changes.

Parameters

Example

varVariable.name := 'exampleVar';
varVariableWatchInst.pVariable := ADR(varVariable);

varVariableWatchInst();

After the function call the uses will be able to see name, value.

varPopulateMemberNames

This is a utility function primarily used by the ATN library. It takes in as its first parameter the name of an existing global structure, and populates all of that structure’s children with string values equal to the names of their variables. The second parameter is an optional prefix length that will strip out the first n characters of the string when assigning the final value to the PV.

Parameters

Example

varPopulateMemberNames('gCommandsApi', 0);

variableBrowser

The function block varVarVariableBrowser() is used to cyclically monitor the value within a varVariable_typ structure. This function allows for monitoring and updating members of an Array or Structure, which is not supported by varGetValue() or varSetValue(). This function block has three inputs pVariable which points at the varVariable_type address, the index of the varVariable_type to be manipulated, and a BOOL that allows for moving up levels within a structure. Parameters

Example

exampleArray[0] := 'test_1';
exampleArray[1] := 'test_2';


VariableWatchInst.pVariable := 'exampleArray';
VariableWatchInst.MemberIndex := UserInput; //-1
VariableWatchInst.Back := UserOption; //false

VariableWatchInst();

After this function call the user would see:

• VariableWatchInst.CurrentVariable = ’exampleArray’
• VariableWatchInst.MemberName = [’exampleArray[0]’, ’exampleArray[1]’]
• VariableWatchInst.MemberValue = [’test_1’, ’test_2']
• VariableWatchInst.MemberInfo = [{ name: “exampleArray[0]”, value: ’test_1' }, { name: “exampleArray[1]”, value: ’test_2' } ]
• VariableWatchInst.NumberMembers = 2
• VariableWatchInst.info = {name: “exampleArray”, value: ‘’, dimension: 1}

// Example continued
VariableWatchInst.MemberIndex := UserInput; //1

VariableWatchInst();

After this function call the user would see:

• inst.CurrentVariable = ’exampleArray[0]’
• inst.MemberName = ''
• inst.MemberValue = ''
• inst.MemberInfo = ''
• inst.NumberMembers = 0
• inst.info = {name: “exampleArray[1]”, value: ’test_2’, dimension: 1}