Community articleUFLDereferenceEx function
Added by IBM contributorIBM on August 16, 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.



Description

Use this function to locate a particular formNodeP, to locate a cell in a particular group, or to locate a data item in a particular datagroup.
Note: It is not necessary to call this function when you are working with an XForms data model. The UFLUpdateXFormsInstance and UFLExtractXFormsInstance functions perform this task automatically.

Function

   formNodeP UFLDereferenceEx(
      formNodeP aNode,
      r_charP theScheme,
      r_charP theReference,
      r_short theReferenceCode,
      r_u_long referenceType,
      formNodeP theNSNode
   );


Parameters

Table 1. Function parameters
ExpressionTypeDescription
aNode formNodePThe node to use as the starting point for the search.
theSchemer_charPReserved. This must be NULL.
theReferencer_charPThe reference string.
theReferenceCoder_shortReserved. This must be 0.
referenceTyper_shortOne 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.
theNSNodeformNodePA node that is used to resolve the namespaces in the theReference parameter (see the note about namespace below). Use NULL if the node that this function is operating on has inherited the necessary namespaces.


Returns

On success: the formNodeP defined by the reference string or NULL if the referenced node does not exist and UFL_SEARCH_AND_CREATE is not specified.

Notes

formNodeP
Before you decide which formNodeP to use this function on, be sure you understand the following:
  1. The formNodeP 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 formNodeP can be no higher in the hierarchy than an item.
  2. If the formNodeP 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 formNodeP 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 formNodeP and the reference string), the function will fail. For example, given a formNodeP 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. UFLDereferenceEx does not support the XForms scheme.
Creating a reference string
For general information about creating a reference string, see About references .
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 UFLDereferenceEx 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:
   error = UFLDereferenceEx(Label1Node, NULL, "Field1.processing:myValue", 
      0, UFL_OPTION_REFERENCE, NULL)

In this example, the UFLDereferenceExfunction 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:
   error = UFLDereferenceEx(Label1Node, NULL, "Field1.processing:myValue", 
      0, UFL_OPTION_REFERENCE, Field1Node)


Example

In the following example, UFLDereferenceEx is used to locate a specific node. UFLDestroy is then used to remove that node from the form structure.
   r_error removeRadios(formNodeP form)
   {
   formNodeP tempNode;
   r_error error;
 
      if ((tempNode =UFLDereferenceEx(form, NULL, "PAGE1.MALERADIO", 0,
         UFL_ITEM_REFERENCE, NULL)) == NULL)      
      { 
         fprintf(stderr, "Could not locate MALERADIO node.\n"); 
         return(NOTOK);
      } 
 
      error = UFLDestroy(tempNode);
      if (error != OK) 
      { 
         fprintf(stderr, "UFLDestroy error %hd.\n", 
            error); 
         return(NOTOK); 
      } 
 
      /* additional code removed */
 
   }


Parent topic:
FormNodeP functions