Description 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.
Table 1. Function parameters
|aNode ||formNodeP||The node to get a reference for.|
|theScheme||r_charP||Reserved. This must be NULL.|
|theNSNode||formNodeP||A 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.|
|theStartPoint||formNodeP||A 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.|
|addNamespaces||r_short||Use 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.|
Returns OK on success or an error code on failure.
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:
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:
<label sid="Label1" xmlns:data="URI">
<field sid="Field1" xmlns:processing="URI">
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, NULL, 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: Page1.Field1.data:myValue. 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:
error = UFLGetReferenceEx(myValueNode, NULL, Label1Node, NULL, NOTOK,
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: Page1.Field1.data:info. 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:
<page sid="Page1" xmlns:processing="URI1">
<field sid="Field1" xmlns:data="URI2">
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:
error = UFLGetReferenceEx(dataNode, NULL, pageGlobalNode, NULL, OK,
You could then store the reference in that global item or any of its descendants, since the namespace is now properly defined.
<global sid="global" xmlns:data="URI2">
Example 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;
/* 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.");