Community articleDereferenceEx function
Added by IBM contributorIBM on July 26, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Description

Use this function to locate a particular IFormNodeP, to locate a cell in a particular group, or to locate a data item in a particular datagroup. The node that this function operates on is used as the starting point of the search.
Note: It is not necessary to call this function when you are working with an XForms data model. The UpdateXFormsInstance and ExtractXFormsInstance functions perform this task automatically.

Function

   Function DereferenceEx(
      theScheme As String, 
      theReference As String, 
      theReferenceCode As Long, 
      referenceType As Long, 
      theNSNode As IFormNodeP
      ) As IFormNodeP


Parameters

Table 1. Function parameters
ExpressionTypeDescription
theSchemeStringReserved. This must be null.
theReferenceStringThe reference string.
theReferenceCodeLongReserved. This must be 0.
referenceTypeLongOne of the following constants:
UFL_PAGE_REFERENCE— Indicates page level nodes. For example, PAGE1.
UFL_ITEM_REFERENCE — Indicates item level nodes. For example, PAGE1.FIELD1.
UFL_OPTION_REFERENCE — Indicates option level nodes. For example, PAGE1.FIELD1.itemlocation.
UFL_ARRAY_REFERENCE — Indicates argument level nodes. For example, PAGE1.FIELD1.itemlocation[2].
UFL_GROUP_REFERENCE — Indicates grouped nodes, such as radio button or checkbox groups. For example, PAGE1.group1.
UFL_DATAGROUP_REFERENCE — Indicates a datagroup node, such as an attachment. For example, PAGE1.datagroup1.
If it is an option or argument reference, you can use bitwise OR ( | ) with one of:
UFL_SEARCH — Searches for the requested node or returns null if the node is not found.
UFL_SEARCH_AND_CREATE — Searches for the requested node or creates one if the node is not found.
If it is a group or datagroup reference, you can use bitwise OR ( | ) with one of:
UFL_FIRST — Finds the first cell or data item in the group or datagroup.
UFL_NEXT — Finds the next cell or data item in the group or datagroup.
UFL_ARRAY_REFERENCE — Indicates argument level nodes. For example, PAGE1.FIELD1.itemlocation[2].
UFL_GROUP_REFERENCE — Indicates grouped nodes, such as radio button or checkbox groups. For example, PAGE1.group1.
UFL_DATAGROUP_REFERENCE — Indicates a datagroup node, such as an attachment. For example, PAGE1.datagroup1.
If it is an option or argument reference, you can use bitwise OR ( | ) with one of:
UFL_SEARCH — Searches for the requested node or returns null if the node is not found.
UFL_SEARCH_AND_CREATE — Searches for the requested node or creates one if the node is not found.
If it is a group or datagroup reference, you can use bitwise OR ( | ) with one of:
UFL_FIRST — Finds the first cell or data item in the group or datagroup.
UFL_NEXT — Finds the next cell or data item in the group or datagroup.
theNSNodeIFormNodePA node that is used to resolve the namespaces in the theReference parameter (see the note about namespace). Use null if the node that this function is operating on has inherited the necessary namespaces.


Returns

The IFormNodeP defined by the reference string or null if the referenced node does not exist and UFL_SEARCH_AND_CREATE is not specified. On error, the function throws an exception.

Usage details

IFormNodeP
Before you decide which IFormNodeP to use this function on, be sure you understand the following:
  1. The IFormNodeP supplied can never be more than one level in the hierarchy above the starting point of the reference string. For example, if the reference string begins with an option, then the IFormNodeP can be no higher in the hierarchy than an item.
  2. If the IFormNodeP is at the same level or lower in the hierarchy than the starting point of the reference string, the function will attempt to locate a common ancestor. The function will locate the ancestor of the IFormNodeP that is one level in the hierarchy above the starting point of the reference string. The function will then attempt to follow the reference string back down through the hierarchy. If the reference string cannot be followed from the located ancestor (for example, if the ancestor is not common to both the IFormNodeP and the reference string), the function will fail. For example, given a IFormNodeP that represents field_1 and a reference of field_2, the function will access the page node above field_1, and will then try to locate field_2 below that node. If the two fields are not on the same page, the function fails.
  3. DereferenceEx does not support the XForms scheme.
Creating a reference string
For general information about creating a reference string, see About references API 801 COMCreate New Article .
Reference strings for groups or datagroups follow this format:
   page.group. or page.datagroup

In both cases, the page component is optional. It is only required if you want to search a different page than the one containing your reference node.
For example, to refer to the "State" group of cells on PAGE1 of the form, use:
   PAGE1.State

Locating cells or data items
If you want to locate a cell or a data item, you must perform a bitwise OR with UFL_FIRST or UFL_NEXT. UFL_FIRST will locate the first cell or data item in the page. UFL_NEXT will locate the next cell or data item. This allows you to loop through all the cells or data item on a page until you have found the one you want.
Note that groups and datagroups are limited to a single page, and that your search will likewise be limited to a single page.
Creating a node
For an option or argument reference, you can have the library create a node that does not exist. To do so, perform a bitwise OR of UFL_SEARCH_AND_CREATE to the referenceType parameter; otherwise, perform a bitwise OR of UFL_SEARCH to the referenceType variable and the function will return null if the node does not exist.
Determining namespace
In some cases, you may want to use the DereferenceEx function to locate a node that does not have a globally defined namespace. For example, consider the following form:
   <label sid="Label1">
      <value>Field1.processing:myValue</value>
   </label>
   <field sid="Field1" xmlns:processing="URI">
      <value></value>
      <processing:myValue>10<processing:myValue>
   </field>

In this form, the processing namespace is declared in the Field1 node. Any elements within Field1 will understand that namespace; however, elements outside of the scope of Field1 will not.
In cases like this, you will often start your search at a node that does not understand the namespace of the node you are trying to locate. For example, you might want to locate the node referenced in the value of Label1. In this case, you would first locate the Label1 value node and get its literal. Then, from the Label1 value node, you would attempt to locate the processing:myValue node as shown:
   Label1Node.DereferenceEx(vbNullString, "Field1.processing:myValue", 0,
      UFL_OPTION_REFERENCE, vbNullString)

In this example, the DereferenceEx function would fail. The function cannot properly resolve the processing namespace because this namespace is not defined for the Label1 value node. To correct this, you must also provide a node that understands the processing namespace (in this case, any node in the scope of Field1) as the last parameter in the function:
   Label1Node.DereferenceEx(vbNullString, "Field1.processing:myValue", 0,
      UFL_OPTION_REFERENCE, Field1Node)


Example

The following example adds a label to a form. A node is passed into the function, which then uses GetLiteralByRefEx to read the value of a field. The function then uses DereferenceEx to locate the field node, and creates a label node as a sibling using Create. Finally, the function creates a value for the new label node using SetLiteralByRef.
   Sub AddLabel(Form)
 
      Dim TempNode, XFDL ' objects
      Dim Name ' strings
 
      Set TempNode = Form
      
      ' Get the value of the NameField.value option node
 
      Name = TempNode.GetLiteralByRefEx(vbNullString, _
         "PAGE1.NameField.value", 0, vbNullString, Nothing)
 
      ' Locate the NameField item node in the first page of the form
      
      Set TempNode = TempNode.DereferenceEx(vbNullString, _
      "PAGE1.NameField", 0, UFL_ITEM_REFERENCE, Nothing)
      
      ' Get an XFDL object
      
      Set XFDL = CreateObject("PureEdge.xfdl_XFDL")
      
      ' Create a label.  This label is created as a sibling of the NameField,
      ' and is named NameLabel.
      
      Set TempNode = XFDL.Create(TempNode, UFL_AFTER_SIBLING, "label", _
         vbNullString, vbNullString, "NameLabel")
      
      ' Create a value option for the label.  This option is assigned the 
      ' value of Name (as read from the field)
      
      TempNode.SetLiteralByRefEx vbNullString, "value", 0, vbNullString, _
         Nothing, Name
   End Sub


Parent topic:
FormNodeP functions