Functions to Operate with Tags
server.GetAttributeTagByNumber
server.GetAttributeTagByRelativeName
server.WriteCurrentTagToDevice
server.WriteTagByNumberToDevice
server.WriteTagByRelativeNameToDevice
server.WriteTagByRelativeNameToHda
If a tag function produces a fatal error, the script error flag is turned on, and that script will not be executed later.
Definitions of tag number, a full tag name and a relative tag name are given in the section Hierarchy of Tree Objects .
This function is similar to server.GetAttributeTag , it returns a table of parameters of the current tag.
Example
local err,t;
err,t = server.GetAttributeCurrentTag( );
Returns attributes (properties) of arbitrary tag by a full name of that tag. The function argument is a full path to a tag.
The function returns:
The error flag: true – error when getting a tag (the tag does not exist), false – there is no an error
A table of attributes. That table contains 11 tag properties:
A short tag name (for instance, "Tag1")
A full tag name (including a node, devices, sub-devices and tag groups – for example, "Node3.Device1.Tag1")
A tag comment
A tag region (for example, "Holding_Registers", "Input_Registers", "Server_Only")
Number of a register to be read out (always 0 in case of "Server_Only")
Number of a register to be written to. If writing to a separate register is off, that register is the same as a register to be read out. Always 0 in case of "Server_Only".
A data type in the device (for example, "int16", "int32"). Always "none" in case of "Server_Only".
A data type in the server (for example, "int16", "int32")
An access type ("ReadOnly", "WriteOnly" or "ReadWrite")
Available for request (true – available, false – unavailable)
HDA access (true – the tag is a HDA tag, false – the tag is a DA tag)
Example
local err,Tab=server.GetAttributeTag("Node2.Device1.Tag1");
-- the err variable contains the error flag; Tab is a table with all tag attributes
server.GetAttributeTagByNumber
Returns the attributes (properties) of an arbitrary tag by its number. The function can return the parameters of the tags of the current node, device or sub-device (depending on where it is called), or it can return the parameters of a specific node or device to which the path is specified.
The function has two input arguments:
tag number (numbering from zero);
path to the node or device. This attribute is optional; if it is not specified, the node or device where the script being called is used.
The function returns:
The error flag: true – error when getting a tag (the tag does not exist), false – there is no an error
A table of attributes. A table structure is identical to a table of the function server.GetAttributeTag .
Example
local err,Tab=server.GetAttributeTagByNumber(1);
-- the err variable contains the error flag; Tab is a table with all tag attributes
server.GetAttributeTagByRelativeName
Returns attributes (properties) of arbitrary tag by a relative name of that tag. The function argument is a relative path to a tag.
The function returns:
The error flag: true – error when getting a tag (the tag does not exist), false – there is no an error
A table of attributes. A table structure is identical to a table of the function server.GetAttributeTag .
Example
local err,Tab=server.GetAttributeTagByNumber(1); --attributes of tag #1 of the current node or device
local err,Tab=server.GetAttributeTagByNumber(1,"Node1"); --attributes of tag #1 of node "Node1"
--the err variable contains the error flag; Tab is a table with all tag attributes
Returns a total number of tags in a node, device or sub-device, depending on what script invokes the function.
Example
CT = server.GetCountTags();
In a tag script, the function returns 1.
This function returns TRUE if a value is written to the tag from a script.
This function returns FALSE if an OPC client writes a value to the tag.
Example
FromScript=server.IsWriteFromScript( );
Returns a value, a quality and a timestamp of the current tag.
Example
TV,TQ,TS = server.ReadCurrentTag();
Returns a value, a quality and a timestamp of arbitrary tag by its name.
Example
TV,TQ,TS = server.ReadTag("Node.Device.Group.Tag");
In this function (as in server.WriteTag ), the following pseudo-names of the current node, device or sub-device can be used:
$(N) – the current node
$(D) – the current device
$(S) – the current sub-device
Examples
Below are examples of functions if the object tree is configured in the following way:
NODE1
DEVICE1
SUBDEVICE1
TEG1
SUBDEVICE2
TEG1
TEG1
--Script of the DEVICE1 device summarizes 2 tags
--and write the result to the tag NODE1.DEVICE1.TEG1
t1,q1,ts1 = server.ReadTag("$(N).$(D).SUBDEVICE1.TEG1");
t2,q2,ts2 = server.ReadTag("$(N).$(D).SUBDEVICE2.TEG1");
server.WriteTag("$(N).$(D).TEG1",t1+t2,192);
--Script of the SUBDEVICE1 sub-device
--reads the tag NODE1.DEVICE1.TEG1
t1,q1,ts1 = server.ReadTag("$(N).$(D).TEG1");
--Script of the SUBDEVICE1.TEG1 tag
--reads the tag NODE1.DEVICE1.TEG1
t1,q1,ts1 = server.ReadTag("$(N).$(D).TEG1");
Returns a value, a quality and a timestamp of a tag by a number of that tag.
Example
TV,TQ,TS = server.ReadTagByNumber(1);
In a tag script, this function returns a value of the current tag regardless of its number.
Returns a table that contains a HDA tag archive. This function is mostly destined to read out archives for next forming an SQL query and transferring data to various DBMSs using functions from the section ODBC.
Function arguments are
Tag name - a full name of a tag with an HDA archive.
Timestamp - data are retrieved from an archive up to that timestamp (a value that has exactly that timestamp is not retrieved). If nil is passed, the whole HDA archive is returned.
Time type - a time type of an archive returned (local or UTC). If False, all timestamps are local, if True, UTC.
Values returned are
Number of HDA records read out
A table of strings read out from HDA records (see below for details)
A timestamp of the last HDA value
The main parameter is a table of strings read out from HDA. That table consists of the following 3 nested tables:
The table "Values" - values of a variable. For convenient forming an SQL query, values are returned in the STRING format, so that additional transformations are not required.
The table "Quality tags" - quality tags of a variable read out. The quality attribute is returned in string format. String examples:
0x000400c0 - GOOD
0x00040040 - Uncertain
0x00040000 - Bad
The table "Timestamps" - a timestamp of a variable. For convenient forming an SQL query, a timestamp is returned as a string as well.
Example
TimeStart=nil; --initialize nil
-- handling
function OnBeforeReading()
Num,Archive,TimeLast=server.ReadHDAFromTag("Simulator.script.Saw",TimeStart,false); --read out value from HDA archive of a variable
if Num==0 then return; end; --exit if there are no data
Values=Archive[1]; --get a table of values
Qual=Archive[2]; --get a table of quality tags
Times=Archive[3]; --get a table of timestamps
for i=1,table.maxn(Values),1 do --search tables and output data
server.Message("table. Values=",Values[i]," Qual=",Qual[i]," Times=",Times[i]);
end;
TimeStart=TimeLast; --save the last timestamp in order to begin to read starting from that timestamp later on
end
See also the example of operation of that function in the section Operation via ODBC.
Returns a value, a quality and a timestamp of a tag by a relative name of that tag.
Example
t, q, ts = server.ReadTagByRelativeName("TagName");
If an error is detected, the function returns the follows: value=nil, quality=0, and ts=<error text>.
Analog of server.SetDeviceToOnOff . This function is used to stop/start execution of a tag.
This function allows you to omit N next tag poll cycles (N is an argument value). For example, this function is usefull if, after writing to a device, the first cycle returns an incorrect value (typical for OWEN TRM2XX).
Example
server.SkipNextCycles(2)
Cancels change of a value of the current tag (restores a previous tag value).
Example
If a tag contains the following script: after the server is switched to the execution mode, and 101 is assigned to the tag, a tag value becomes equal to 10 again, and a tag quality, OPC_QUALITY_GOOD.
function OnInit()
server.WriteCurrentTag(10, OPC_QUALITY_UNCERTAIN);
end
function OnClose()
end
function OnRead()
if server.ReadCurrentTag( ) > 100 then
server.UndoCurrentTag( );
end
end
The function returns nothing.
Writes a value and a quality to the current tag.
Example
server.WriteCurrentTag(TV,TQ);
The function returns nothing.
server.WriteCurrentTagToDevice
Writes a value and a quality to the current tag, addressing to a device.
Example
server.WriteCurrentTagToDevice(TV,TQ);
The function returns nothing.
Writes the following parameters into a HDA archive of the current tag: a specified value, a specified quality, and (optionally) a specified timestamp (a timestamp is specified as an 8-byte array, see time.StringToTimeStamp and time.TimeToTimeStamp ). In the tag, the flag to write to HDA archive must be set on (HDA Access=TRUE; see The Dialog of Tag Parameters ).
Examples
Writing of 120 with the quality OPC_QUALITY_GOOD and with current OS time:
res=server.WriteCurrentTagToHda(120,192);
Writing of 120 with the quality OPC_QUALITY_GOOD and with the specified timestamp:
ts = time.StringToTimeStamp("2010-05-03 12:34:45.100");
res= server.WriteCurrentTagToHda(120,192,ts);
Writing of 120 with the quality OPC_QUALITY_COMM_FAILURE and with the specified timestamp:
timesec = os.time{year=2010,month=05,day=03,hour=12,min=34,sec=45};
timemsec=200;
ts = time.TimeToTimeStamp(timesec,timemsec);
server.WriteCurrentTagToHda(120,OPC_QUALITY_COMM_FAILURE,ts)
Writes a value and a quality to a tag by a full name of that tag.
Example
server.WriteTag("Node.Device.Group.Tag",TV,TQ);
The function returns nothing.
In this function (as in server.ReadTag ), pseudo-names of the current node, device or sub-device may be used.
Writes a value and a quality to a tag by a number of that tag.
Example
server.WriteTagByNumber(1,TV,TQ);
The function returns nothing. In a tag script, the function writes a value to the current tag.
server.WriteTagByNumberToDevice
This function is similar to server.WriteTagByNumber , but addressing to a device.
Writes the following parameters to a HDA archive of a tag by a number of that tag: a specified value, a specified quality, and (optionally) a specified timestamp (a timestamp is specified as an 8-byte array, see time.StringToTimeStamp and time.TimeToTimeStamp ). In the tag, the flag to write to HDA archive must be set on (HDA Access=TRUE; see The Dialog of Tag Parameters ).
Examples
Writing of 5 with the quality OPC_QUALITY_BAD and with the current OS time into the HDA archive of the tag number 2:
res=server.WriteTagByNumberToHda(2, 5, OPC_QUALITY_BAD);
Writing of 5 with the quality OPC_QUALITY_BAD and with the specified timestamp into the HDA archive of the tag number 2:
ts = time.StringToTimeStamp("2010-05-03 12:34:45.100");
res=server.WriteTagByNumberToHda(2, 5, OPC_QUALITY_BAD,ts);
Writes a value and a quality to a tag by a relative name of that tag.
Example
res = server.WriteTagByRelativeName("TagName", t, q);
In case of successful writing, the function returns true, and false otherwise.
server.WriteTagByRelativeNameToDevice
Writes a value and a quality to a tag by a relative name of that tag, and initiates writing to a device.
Example
res = server.WriteTagByRelativeNameToDevice("TagName", t, q);
In case of successful writing, the function returns true, and false otherwise.
server.WriteTagByRelativeNameToHda
Writes the following parameters to a HDA archive of a tag by a relative name of that tag: a specified value, a specified quality, and (optionally) a specified timestamp (a timestamp is specified as an 8-byte array, see time.StringToTimeStamp and time.TimeToTimeStamp ). In the tag, the flag to write to HDA archive must be set on (HDA Access=TRUE; see The Dialog of Tag Parameters ).
Examples
Writing of 5 with the quality OPC_QUALITY_BAD and with the current OS time into a HDA archive of the tag TAG1 from a script of the node NODE1 that contains the device DEVICE1:
res=server.WriteTagByRelativeNameToHda("DEVICE1.TAG1", 5, OPC_QUALITY_BAD);
Writing of 5 with the quality OPC_QUALITY_BAD and with the specified timestamp into a HDA archive of the tag TAG1 from a script of the device DEVICE1 or from a script of a tag of the device DEVICE1:
ts = time.StringToTimeStamp("2010-05-03 12:34:45.100");
res=server.WriteTagByRelativeNameToHda("TAG1", 5, OPC_QUALITY_BAD,ts);
Writes a value and a quality to a tag by a full name of that tag, addressing to a device.
Example
server.WriteTagToDevice("Node.Device.Group.Tag",TV,TQ);
The function returns nothing.
Writes the following parameters to a HDA archive of a tag by a full name of that tag: a specified value, a specified quality, and (optionally) a specified timestamp (a timestamp is specified as an 8-byte array, see time.StringToTimeStamp and time.TimeToTimeStamp ). In the tag, the flag to write to HDA archive must be set on (HDA Access=TRUE; see The Dialog of Tag Parameters ).
Examples
Writing of 5 with the quality OPC_QUALITY_BAD and with the current OS time:
res=server.WriteTagToHda("Node1.Device1.Tag1", 5, OPC_QUALITY_BAD);
Writing of 5 with the quality OPC_QUALITY_BAD and with the specified timestamp:
ts = time.StringToTimeStamp("2010-05-03 12:34:45.100");
res=server.WriteTagToHda("Node1.Device1.Tag1", 5, OPC_QUALITY_BAD,ts);
In case of successful writing, the function returns true, and false otherwise.
Reads a set of tags whose names are defined in the function's input table. This function should be used when reading a large amount of tags (several hundred or more) - in this case, the processing of values is significantly accelerated.
Input arguments:
Table with tag names;
A prefix that is added to the name of each tag (for example, the path to the device where the tags are located). It should be remembered that if a path to a node/device is specified, then a dot must be added at the end of the prefix - "SCRIPT.script."
Output arguments:
Table of reading results. Each table element contains another table with the following fields:
The full path to the tag. If a tag has a prefix, it is removed from the tag name.
Tag value;
Tag quality;
Tag timestamp.
In case of an error it returns nil.
Examples
--name tags
local TagNames={"SCRIPT.script.Tag1","SCRIPT.script.Tag2","SCRIPT.script.Tag3"};
local TagsValues=server.ReadTagsByTable(TagNames,""); --read tags
if TagsValues==nil then --check read
server.Message("Error read tags");
return;
end;
--iterating tags
for i=1,table.maxn(TagsValues),1 do
local TagValue=TagsValues[i];
--write values to log
server.Message("Name=",TagValue[1]," Value=",TagValue[2]," Quality=",TagValue[3]," Time=",time.TimeStampToString(TagValue[4]));
end
In the example, the tags are pre-written in the table TagNames, if you want to collect specific tags of the node, then use the function server.GetAttributeTagByNumber.
Writes a table (array) of values into tags. This function should be used when writing a large amount of tags (several hundred or more) - in this case the writing of values to the tags is significantly accelerated.
Input arguments:
A table with the following fields:
Full tag path;
Tag value;
Tag quality;
The tag's time stamp is an optional parameter; if not specified, it will be recorded with the current time.
A prefix that is added to the name of each tag (e.g. the path to the device where the tags are located). Remember that if the path to the node/device is specified, you must add a dot at the end of the prefix - "SCRIPT.script."
Примеры
--name tags
local TagNames={"SCRIPT.script.Tag1","SCRIPT.script.Tag2","SCRIPT.script.Tag3"};
local TagsValues={};
for i=1,table.maxn(TagNames),1 do
local TagValue={};
TagValue[1]=TagNames[i]; --full name tag
TagValue[2]=math.random(0,100 ); --random value tag
TagValue[3]=OPC_QUALITY_GOOD; --quality
TagValue[4]=time.TimeStampNow( ); --timestamp
table.insert(TagsValues,TagValue); --add to table
end
server.WriteTagsByTable(TagsValues,""); --write to tags
In the example, the tags are pre-written in the table TagNames, if you want to collect specific tags of the node, then use the function server.GetAttributeTagByNumber.