Reading the Linkage off of an Element

A common task when programming with GTViewer or GTVx is to get the Linkage off of an element (for more info on linkages, look here). For example, if an event were fired indicating that an element had been selected, you get the Category Id and the Element Offset of the selected element as parameters in the event. So, how do you get the Linkage stored on the element so that you can lookup database information? It turns out that there are several ways to do this, but I am going to provide a generic approach that should work for most cases.

It turns out that there is a method provided by both GTViewer and GTVx to retrieve the linkage from an element. It is aptly named GetElementLinkage; however, it returns an array of linkage values (since GTViewer data can have 1 to 7 linkage values per element). Most datasets use a 1 or 2 key linkage system and it sometimes, so it sometimes seems cumbersome to deal with an array when you know you will always be getting one or two linkage values. It is pretty easy to write a function in VB to just return you the one key or two keys without having to deal with the array. The example below is for 2 keys, but it should be obvious how to downgrade this code to a 1 key version.

Function GetElementLinkage(ByVal categoryId As Long, _
ByVal offset As Long, _
dataId As Long, _
key1 As Long, key2 As Long) As Boolean

' This function will get the linkage off of the element specified by its
' categoryId and offset. The dataId, key1, and key2 values will be populated.
' If the element contains only a 1 key linkage, key2 will be 0.
' The function returns True if a linkage was found and False otherwise.

GetElementLinkage = False

Dim linkageList As Variant
Dim linkCount As Long

key1 = 0
key2 = 0

If docObj.GetElementLinkage(categoryId, offset, linkageList, linkCount) Then

dataId = docObj.GetDataId(categoryId)

If linkCount > 0 Then

key1 = linkageList(0)

If linkCount > 1 Then

key2 = linkageList(1)

End If

GetElementLinkage = True

End If

End If

End Function


The function above is for GTViewer, but it is very easy to use it with GTVx as well. You can either change the docObj reference to a GTVx1 (or whatever variable name you assigned to the control) or you can add something like the following to your code and use the same code for both GTViewer and GTVX. Write your code for GTViewer making sure to use the correct object when calling the methods (appObj, docObj, or viewObj). For GTVx, just define variables like the ones below in your general section:

Dim appObj As GTVx
Dim docObj As GTVx
Dim viewObj As GTVx

And somewhere in your code, assign the object variables to the GTVx control (Form_Load is a good place to do this):

Private Sub Form_Load()

Set appObj = GTVX1
Set docObj = GTVX1
Set viewObj = GTVX1

.
.
.

End Sub

That is all you have to do. The function is provided in an appendix to the GTVx.doc file. There are other useful code snippets in this document as well.