Community articleUFLGetReferenceEx 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


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.


   r_short UFLGetReferenceEx(
      formNodeP aNode,
      r_charP theScheme,
      formNodeP theNSNode,
      formNodeP theStartPoint,
      r_short addNamespaces,
      r_charP *theReference


Table 1. Function parameters
aNode formNodePThe node to get a reference for.
theSchemer_charPReserved. This must be NULL.
theNSNodeformNodePA 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.
theStartPointformNodePA node that determines the starting point of the reference. This node must be a parent of the aNode parameter. 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.
addNamespacesr_shortUse OK to add declarations for unknown namespaces to the namespace node (theNSNode). Otherwise, use NOTOK.
theReference r_charP*A pointer that will store the reference. This string must be freed by the caller.


OK on success or an error code on failure.

Usage details

Creating a reference string:
For more information about creating a reference, see About references .
Working with namespace prefixes:
In some cases, you may want to use the UFLGetReferenceEx 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:
   error = UFLGetReferenceEx(myValueNode, NULL, NULL, NULL, NOTOK, 

In this case, UFLGetReferenceEx 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 UFLGetReferenceEx function. The second node must understand the appropriate namespace. For example, you could include the Label1 node in the function, as shown:
   error = UFLGetReferenceEx(myValueNode, NULL, Label1Node, NULL, NOTOK, 

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 UFLGetReferenceEx 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. UFLGetReferenceEx 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 UFLGetReferenceEx function. When this flag is set to OK, 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 OK, as shown:
   error = UFLGetReferenceEx(dataNode, NULL, pageGlobalNode, NULL, OK, 

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.


In the following example, a page node is passed to the function. The function then uses UFLGetChildren and UFLGetNext to locate the last item node in the page. UFLGetReferenceEx is then called to get the reference to that node, which is returned to the caller.
   r_charP getLastItemReference(formNodeP pageNode)
   formNodeP itemNode, tempNode;
   r_charP theReference;
      /* Get the first item node in the page. */
      if ((itemNode = UFLGetChildren(pageNode)) == NULL)
         fprintf(stderr, "Could not locate child node.");
      /* Cycle through to the last item node in the page. */
      while ((tempNode = UFLGetNext(itemNode)) != NULL)
         itemNode = tempNode;
      /* Get the reference to the node and return it. */
      if (UFLGetReferenceEx(itemNode, NULL, NULL, NULL, NOTOK, 
         &theReference) != OK)
         fprintf(stderr, "Could not get reference to node.");

Parent topic:
FormNodeP functions