Community articleUFLUpdateXFormsInstance function
Added by IBM contributorIBM on May 2, 2012
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars


Updates the XForms model by inserting, replacing, deleting, or appending data anywhere within the XForms instance data. Call this function on the root node of the form.
Note: Use caution when calling this function. It can silently break a digital signature if signed instance data is modified.


   r_short UFLUpdateXFormsInstance(
      formNodeP theObject,
      r_charP theModelID,
      r_charP theNodeRef,
      formNodeP *theNSNode,
      r_charP theFilename,
      r_byte *theMemoryBlock,
      r_long theMemoryBlockSize
      r_u_long updateType


Table 1. Function parameters
theObject formNodePThe formNodeP object.
theModelIDr_charPThe ID of the model to update. If NULL or empty, the default model is updated.
theNodeRefr_charPAn XPath reference to a node in the instance that you want to update. An empty string indicates the document node of the default instance of the selected model.
theNSNodeformNodePThis node defines the namespaces for the function. Use NULL if the node that this function is operating on has inherited the necessary namespaces.
theFilenamer_charPThe file to read the instance data from. This file must be UTF-8. Note that if both a file and a memory block are provided, the file will take precedence.
theMemoryBlockr_byteThe memory block that contains the instance data. Use NULL if you are reading from a file, input stream, or Reader.
theMemoryBlockSize r_longThe size of theMemoryBlock.
updateTyper_u_longOne of the following constants:
XFORMS_UPDATE_REPLACE — Replaces the node that is referenced by theNodeRef with the input instance data.
XFORMS_UPDATE_REPLACE_TEXT — Replaces the string value of the node that is referenced by theNodeRef with the input data.
XFORMS_UPDATE_APPEND — Adds the input data as the last child node of the node that is referenced by theNodeRef.
XFORMS_UPDATE_INSERT_ BEFORE — Adds the input data as a sibling before the node that is referenced by theNodeRef. You cannot insert data before the root element of the instance.
XFORMS_UPDATE_DELETE — Deletes the node that is referenced by theNodeRef. You cannot delete the entire instance.
If used, the following flags must be used in conjunction with one of the updateType flags described above:
XFORMS_DEFER MODEL_UPDATE — Marks the model for a deferred update. In a deferred update, the data model is not changed immediately; instead, the model is flagged to indicate that there are changes that need to be implemented. To enact a deferred update and implement the changes to the model, use the UFLXFormsModelUpdate function.
XFORMS_SUPPRESS_MODEL_UPDATE — Prevents any automatic updating of the model. See the "Notes®" section below for usage details.
Note: You can only use the XFORMS_DEFER MODEL_UPDATE and XFORMS_SUPPRESS_MODEL_UPDATE flags when XForms processing is turned on.


OK on success or an error code on failure.

Usage details

Modifying the XForms data model
The UFLUpdateXFormsInstance function and the UFLExtractXFormsInstance functions are the only functions that are intended to modify the XForms data model.
Default behavior of the function
When the updateFlags parameter is set to 0, UFLUpdateXFormsInstance performs its default behavior. However, this default behavior varies depending on how the form is loaded:
  • If the form is opened without using the function, or the form is loaded using the function but the flags parameter is set to 0, then UFLUpdateXFormsInstance automatically updates the data model each time that a change is made to the model.
  • If the form is loaded using the function with the flags parameter set to UFL_SERVER_SPEED_FLAGS_WITH_XFORMS or UFL_XFORMS_INITIALIZE_ONLY, then UFLUpdateXFormsInstance marks the data model for a later update when a change is made to the model. To enact this update, use the UFLXFormsModelUpdate function.
  • If the form is loaded using the UFLReadForm function with the flags parameter set to UFL_SERVER_SPEED_FLAGS, then UFLUpdateXFormsInstance does not update the data model or mark the model for a later update. You cannot update the data model if XForms processing is turned off completely.
You can override these default behaviors by using the updateFlags parameter.
Suppressing updates to the model
Automatically updating the data model each time that a change is made to the form causes an unnecessary expenditure of computing resources. Each time that UFLUpdateXFormsInstance is called in an application, the function will check every node in the model for potential updates. Use the XFORMS_SUPPRESS_MODEL_UPDATE flag to prevent unnecessary updating, and then call UFLUpdateXFormsInstance without using the XFORMS_SUPPRESS_MODEL_UPDATE flag at the very end of the application to implement all of the model updates with one function call.


The following example shows an XForms instance and a function that you can use to replace it.
Instance data:
   <xforms:instance id="instance1" xmlns="">

   r_error updateDataInstance(formNodeP theForm)
      if (UFLUpdateXFormsInstance(theForm, "model1", 
         "instance('instance1')/user_personal_info", NULL,
         "c:\\InstanceData.xml", NULL, 0, XFORMS_UPDATE_REPLACE) 
         != OK)
         fprintf(stderr, "Could not replace data instance.");

Parent topic:
FormNodeP functions