Edit the tags database during run time

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

There are several important things to keep in mind when using the TagsDB functions, because they 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 clients if it is not done properly. As such, most of the TagsDB functions can be executed only under the following conditions.

First, the InduSoft Web Studio development application must be installed and running on the project server, it must be fully licensed for Engineering+Runtime, and the project must be open in the application. The TagsDB functions use the development application’s database editor in essentially the same way that you do when you manually edit your project during run time. Because of this limitation, the TagsDB functions cannot be used at all in projects designed for and downloaded to Windows Embedded devices.

Second, the TagsDB functions can be called only from scripts executed on the project server. None of the connected clients — not even the project client running on the same computer as the project server, because it runs as a separate process on that computer — can make structural changes to the tags database without interfering with other clients, decreasing run-time performance, and potentially corrupting the database. Therefore, generally speaking:
  • The functions can be called from the Startup Script (which is executed when the project itself is run), Script Groups (which are continuously executed by the Background Task), and any Global Procedures called by them; and
  • The functions cannot be called from the Graphics Script (which is executed separately by each client), Screen Scripts (which are attached to individual screens), and Command animations.
Tip: To work around these restrictions, do one of the following:
  • Create a Global Procedure to call the TagsDB functions, and then call the function RunGlobalProcedureAsync to run that procedure; or
  • Create a Script Group to call the TagsDB functions, configure a tag/expression to control the execution of that Script Group, and then change the value of that tag/expression.

Third, in any script that calls TagsDB functions to make structural changes to the tags database, you must first call the function TagsDBBeginEdit in order to lock the database for editing and prevent any other run-time changes. Then, at the end of the script, you must call the function TagsDBEndEdit in order to finish the changes that were made and allow the database to resume normal run-time behavior. Both functions must be called in the same script, because that script (more specifically, the program thread running that script) effectively owns the tags database while it is locked. You cannot call TagsDBBeginEdit in one script and then call TagsDBEndEdit in another.

When a project is edited during run time, the project server and every connected client must be updated with the changes as they are made. Normally, 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 project server and the connected clients with all of those changes while the project is running can severely decrease run-time performance. Therefore, to maintain performance and protect the tags database, the project runtime — including all background tasks such as alarms, trends, and other scripts — is effectively paused and the changes are applied as a batch.

Note: The function TagsDBBeginEdit has a persistent effect. This means that if you call the function to lock the tags database during project run time and then stop the project, then 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 designed your project and which script locked the database in the first place. Instead, you should use the Database Spy to manually call the function TagsDBEndEdit. When that is executed successfully, you can safely restart your 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

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

Here is another example that 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 everything else when the tag is removed. They are included in the example simply to be thorough. In contrast, the class member and class cannot be removed until the tag is removed successfully.

InduSoft Web Studio -Technical Reference

Edit the tags database during run time