TagsDBPreload

TagsDBPreload is a built-in function that manually preloads a project tag into memory on a project thin client.

Syntax

TagsDBPreload(strTagName)

TagsDBPreload ( strTagName )

strTagName

The name of the project tag that you want to preload. If it is an array and/or class, and if you specify an array position and/or class member, only that position and/or member will be preloaded. Otherwise, all positions and/or members will be preloaded.

Note: If this parameter is enclosed in quotes, the string literal will be used. Otherwise, the value of the tag/expression will be used.

Returned value

If this function is executed successfully, it will return the number (greater than or equal to 1) of tags that are currently selected for preloading. Otherwise, it should return one of the following possible values:

If this function returns a negative value that is not shown in the table above, please contact your software distributor for support.

Notes

Each project thin client maintains a list of project tags to which it is subscribed. Being subscribed to a tag means the client keeps that tag loaded in memory, even when it is not being used, and the project runtime server sends updated tag values to the client only when those values change. This subscription model improves the runtime performance of the client and reduces unnecessary communication between the client and the server.

When the client opens a project screen for the first time, it automatically adds the project tags used in that screen to its subscription list. More specifically, the client does the following: it examines all of the objects and scripts included in the screen, it determines which tags are referenced by those objects and scripts, it adds those tags to its subscription list, and then it processes the list in order to get the latest values of the tags before it actually displays the screen. The client does all of this to make sure it can open the screen quickly and without errors, both the first time and every time thereafter.

In some cases, however, the client cannot determine for itself all of the tags it needs to add to its subscription list. Objects and scripts in the screen might not initialize correctly, and the screen might open slowly or with errors. When this happens, you can call the TagsDBPreload function to manually preload the missing tags.

For example, if a screen uses a large array tag — that is, an array tag with a large number of elements — it might take an unacceptably long time for the client to load the entire array and then open the screen. You can call this function to preload the specific elements of the array that might be used in the screen, or if you actually need to preload the entire array, you can make sure it is done before the screen is opened. Also, if a screen uses an indirect tag (for example, @MyTag) that has no real value of its own until after the screen is opened and the tag value is resolved, you can can call this function to preload the base tag (for example, MyTag).

You will typically call this function in the Screen_OnOpen sub-routine of the Screen Script for a given screen. Or, if you want to preload the same tag for several different screens, you can also call this function in the Graphics_OnStart sub-routine of the Graphics Script.

You can use this function in conjunction with the TagsDBPreloadWait, TagsDBGetPreloadCount, and TagsDBGetLoadStatus functions to manage the preloading of multiple tags. See "Examples" below.

Once this function is called to preload a tag for a screen, that tag is added to the client's subscription list and it does not need to be preloaded again for that screen or any other screen. If this function is called again for the same tag, it is ignored.

Examples

The following example shows how the TagsDBPreload, TagsDBPreloadWait, TagsDBGetPreloadCount, and TagsDBGetLoadStatus functions can all be used in the Screen_OnOpen sub-routine of the Screen Script:

Sub Screen_OnOpen()

Dim counter, preloadCount, preloadDone, loadStatus

// Select tags for preloading.

preloadCount = $TagsDBPreload("MyTagA")

preloadCount = $TagsDBPreload("MyTagB")

preloadCount = $TagsDBPreload("MyTagC")

preloadCount = $TagsDBPreload("MyArray[1]")

preloadCount = $TagsDBPreload("MyArray[2]")

preloadCount = $TagsDBPreload("MyArray[3]")

// Wait up to five seconds to load tags.

counter = 0

preloadDone = 0

Do

preloadDone = $TagsDBPreloadWait(1000)

preloadCount = $TagsDBPreloadCount()

counter = counter + 1

Loop Until (preloadDone <> 0) Or (counter = 5)

// Save preload count message to string tag, for later use.

$PreloadCountMsg = preloadCount & " tag(s) waiting to be loaded."

// Save load status message to string tag, for later use.

loadStatus = $TagsDBGetLoadStatus("MyTagA")

If (loadStatus = 2) Then

$LoadStatusMsg = "MyTagA is loaded."

ElseIf (loadStatus = 1) Then

$LoadStatusMsg = "MyTagA is waiting to be loaded."

Else

$LoadStatusMsg = "Error while loading MyTagA."

End If

End Sub