Use TagsDB functions to edit the tags database during run time

Use the Tags Database (TagsDB) functions to add and remove tags, classes, and class members during project run time, as well as to set properties and alarm conditions on tags.

There are several important things to keep in mind when you use TagsDB functions, because the functions can do much more than set and get tag values. They actually change the structure of the tags database, which can cause serious problems for a running project and all connected thin clients if it is not done properly. As such, most TagsDB functions can be executed only under the following limitations.

First, you must use the SCADA runtime edition for Windows to run your project — in other words, you must install the full Studio software on a Windows computer and then license it for either "Engineering+Runtime" or "Runtime only". (You can also license the software for "Engineering only", but your project will run for only 72 hours before it needs to be restarted.) The TagsDB functions use the project development environment's database editor in essentially the same way that you do when you manually edit your project during run time. Due to this limitation, the TagsDB functions cannot be used in projects that are developed for and run on embedded devices.

Second, the TagsDB functions can be called only by scripts that are executed on the project runtime server. The functions cannot be executed on project thin clients because a client cannot make structural changes to the tags database without interfering with other clients, decreasing runtime performance, and potentially corrupting the database. (In this case, "project thin clients" includes the Viewer module that runs on the same computer as the project runtime server, because it runs as a separate process on that computer.) Therefore, generally speaking…

TagsDB functions can be used in:

• The Startup Script, which is executed when the project itself is run;

• Script Groups, which are periodically scanned by the Background Task; and

• Global Procedures that are called by the Startup Script or Script Groups.

TagsDB functions cannot be used in:

• The Graphics Script, which is executed by each project thin client client when it starts;

• Screen Scripts, which are attached to project screens and executed when those screens are opened; and

• Command animations.

To work around this limitation, create a Script Group to call the TagsDB functions and then configure a trigger to control the execution of that Script Group.

Third, in any script that calls TagsDB functions to make structural changes to the tags database, you must call the TagsDBBeginEdit function at the beginning of the script and the TagsDBEndEdit function at the end of the script. The TagsDBBeginEdit function locks the database for editing and prevents any other runtime changes. The TagsDBEndEdit function applies the changes made by TagsDB functions and then allows the database to resume normal runtime behavior. Both functions must be called in the same script, because that script (more specifically, the program thread running that script) owns the tags database while it is locked. You cannot call TagsDBBeginEdit in one script and then call TagsDBEndEdit in another script.

Normally, when a project is edited during run time, the project runtime server and all project thin clients must be updated with the changes as they are made. This is not a problem when you manually edit your project, because you make your changes slowly and one at a time. In contrast, the TagsDB functions allow you to make a large number of changes quickly, so updating the server and clients with all of those changes while the project is running can severely decrease runtime performance. Therefore, to maintain performance and protect the tags database, the server — including all background tasks such as alarms, trends, and other scripts — is effectively paused when the TagsDBBeginEdit function is executed, and then the changes are applied as a batch when the TagsDBEndEdit function is executed. Also, as part of this update process, project screens that were already open on clients will be reopened and their OnOpen screen scripts will be executed again.

Note: The TagsDBBeginEdit function has a persistent effect, which means that if you call the function to lock the tags database during project run time and then stop the project, the database will remain locked and you will not be able to manually edit it.

Restarting the project may or may not unlock the database, depending on how you developed your project and which function call locked the database in the first place. As such, while the project is stopped, you should use the Watch window to manually call the TagsDBEndEdit function. When it is successfully executed, you can safely restart the project.

Examples

The following example shows how to use the TagsDB functions in VBScript to add a new class, then add a new class member to that class, then add a new tag of that class, then set an alarm and a trend on that tag.

If($TagsDBBeginEdit()=0) Then

If($TagsDBAddClass("TempClass")=0) Then

If($TagsDBAddClassMember("TempClass","TempMember","Real")=0) Then

If($TagsDBAddTag("TempTag","TempClass",2,0)=0) Then

If($TagsDBSetAlarm("TempTag[0].TempMember",1,0,3.5)<>0) Then

$Msg = "Alarm not Set"

End If

If($TagsDBSetTrend("TempTag[0].TempMember",0,1)<>0) Then

$Msg = "Trend not Set"

End If

Else

$Msg = "Tag not created"

End If

Else

$Msg = "Class Member not added"

End If

Else

$Msg = "Class not created"

End If

$TagsDBEndEdit()

Else

$Msg = "Tag functions not enabled"

End If

Please note how the script begins with the TagsDBBeginEdit function and then ends with the TagsDBEndEdit function. Also, see how the nested If…Then…Else structures ensure that each function is executed successfully (that is, returns a value of 0) before the next one is attempted.

The following example shows how to remove the alarm, trend, tag, class member, and class, in reverse order from how they were added in the previous example.

If($TagsDBBeginEdit()=0) Then

If($TagsDBRemoveAlarm("TempTag",1)<>0) Then

$Msg = "Alarm not removed"

End If

If($TagsDBRemoveTrend("TempTag")<>0) Then

$Msg = "Trend not removed"

End If

If($TagsDBRemoveTag("TempTag")=0) Then

If($TagsDBRemoveClassMember("TempClass","TempMember")<>0) Then

$Msg = "Class member not removed"

End If

If($TagsDBRemoveClass("TempClass")<>0) Then

$Msg = "Class not removed"

End If

Else

$Msg = "Tag not removed"

End If

$TagsDBEndEdit()

Else

$Msg = "Tag functions not enabled"

End If

It is not absolutely necessary to remove the alarm and trend before removing the tag they are on, because they are discarded with the rest of the tag properties and other metadata when the tag itself is removed. They are included in the example above simply to be thorough. In contrast, the class member and class cannot be removed until every tag in that class is removed.