Community articleGetReferenceEx function
Added by IBM contributorIBM on August 15, 2011
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.


This function returns the reference string that identifies the node. For example, a value node might return a reference of Page1.Field1.value. The reference will either begin at the page level of the form or at a level specified by the caller.


   Function GetReferenceEx(
      theScheme As String, 
      theNSNode As IFormNodeP, 
      theStartPoint As IFormNodeP, 
      addNamespaces As Boolean
      ) As String


Table 1. Function parameters
theSchemeStringReserved. This must be null.
theNSNodeIFormNodePA node that defines which namespace prefixes are used when constructing the reference. Only namespace prefixes that this node inherits are used. Use null if the node that this function is operating on has inherited the necessary namespaces.
theStartPointIFormNodePA node that determines the starting point of the reference. This node must be a parent of the current node. The reference will begin one level below the start point node. For example, if you provide a page node the reference will begin at the item level. Use null to start the reference at the page level.
addNamespacesBooleanUse True to add declarations for unknown namespaces to the namespace node (theNSNode). Otherwise, use False.


A string containing a reference to the node, or throws an exception if an error occurs.


Creating a reference string:
For more information about creating a reference, see About references API 4 COMCreate New Article .
Working with namespace prefixes:
In some cases, you may want to use the GetReferenceEx function to get the reference to a node that uses a different prefix for a known namespace. For example, consider the following form:
   <label sid="Label1" xmlns:data="URI">
   <field sid="Field1" xmlns:processing="URI">

In this form, processing and data are prefixes for the same namespace, since they both refer to the same URI. However, both namespaces have limited scope since they are declared at the item level. This means that Label1 node does not understand the processing prefix, and that the Field1 node does not understand the data prefix.
This becomes a problem if you want to refer to a namespace from a location that does not understand that namespace. For example, suppose you want to set the value of Label1 to be a reference to the myValue node in Field1. Normally, you would locate the myValue node and use getReferenceEx as shown:
   myValueNode.GetReferenceEx(vbNullString, Nothing, Nothing, False)

In this case, GetReferenceEx would return the following reference: Page1.Field1.processing:myValue. However, because the processing namespace is not defined for Label1, a reference to the processing namespace is not understood. This means that you cannot set the value of Label1 to equal this reference, since the node would not understand that content.
Instead, you must generate a reference that includes a known namespace prefix, such as the data namespace. You can do this by including a second node in the GetReferenceEx function. The second node must understand the appropriate namespace. For example, you could include the Label1 node in the function, as shown:
   myValueNode.GetReferenceEx(vbNullString, Label1Node, Nothing, False)

In this case, the function will substitute the data prefix for the processing prefix, since they both resolve to the same namespace. As a result, the function will return: Since the data prefix is defined within Label1, you can use this reference to set Label1's value node.
Working with unknown namespaces:
In some cases, you may want to use the GetReferenceEx function to get the reference to a node that uses an unknown namespace. For example, consider the following form:
   <page sid="Page1" xmlns:processing="URI1">
      <global sid="global">
      <field sid="Field1" xmlns:data="URI2">

In this example, you might want to store a reference to the <data:info> element in the <processing:info> element. GetReferenceEx would return the following reference for the <data:info> element: However, this reference includes the data namespace, which is not defined for the page global. This means that you could not store this reference in the <processing:info> element, because it would not understand the reference.
To solve this problem, you can use the addNamespaces flag in the GetReferenceEx function. When this flag is set to True, the function will add unknown namespaces to the theNSNode.
For example, if you set theNSNode to be the global item node for Page1, and set the addNamespace flag to True, as shown:
   dataNode.GetReferenceEx(vbNullString, pageGlobalNode, Nothing, True)

The function would return the reference to the <data:info> element, but would also modify the global item node to include the unknown data namespaces, as shown:
   <global sid="global" xmlns:data="URI2">

You could then store the reference in that global item or any of its descendants, since the namespace is now properly defined.


The following sample function receives any form node and returns a reference to the last page of the form. First, the function uses GetNodeType to determine if the supplied node is a the form level. If so, the function uses GetChildren to locate the first page node. If not, the function uses GetParent to locate a page level node. The function then uses GetNext to locate the last page in the form and calls GetReferenceEx to retrieve a reference to that node.
   Function GetLastPage(Node)
      Dim MainNode, TestNode ' objects
      Set MainNode = Node
      ' Locate the page level node that is the nearest ancestor or child of
      ' the current node.  If the node is a form node, get the child.  If the
      ' node is any other type, get the parent until a page node is 
      ' retrieved.
      If MainNode.getNodeType = UFL_FORM Then 
         Set MainNode = MainNode.GetChildren
         ' Locate the page node of the form by iterating through the parents
         ' of the supplied node.  At the end of this loop, MainNode will be
         ' a page node.
         Do While (Not(MainNode.GetNodeType = UFL_PAGE))
            Set MainNode = MainNode.GetParent
      End If
      ' Set TestNode to be the MainNode (the page node) before beginning the
      ' next loop.
      Set TestNode = MainNode
      ' Locate the last page node by iterating through the siblings of the
      ' global page node.  At the end of this loop, TestNode will be Nothing
      ' and MainNode will be the last page node.
      Do While (Not(TestNode Is Nothing))
         Set MainNode = TestNode
         Set TestNode = TestNode.GetNext
      ' Get a reference to the MainNode and return that reference to the
      ' caller.
      GetLastPage = MainNode.GetReferenceEx(vbNullString, Nothing, Nothing,_
   End Function

Parent topic:
FormNodeP functions