Community articleUpdateXFormsInstance function
Added by IBM contributorIBM on August 15, 2011
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.


   Sub UpdateXformsInstance(
      theModelID As String, 
      theNodeRef As String, 
      theNSNode As IFormNodeP, 
      theFilename As String, 
      theMemoryBlock As Variant,
      updateType As Long)


Table 1. Function parameters
theModelIDStringThe ID of the model to update. If vbnullstring or empty, the default model is updated.
theNodeRefStringAn 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.
theNSNodeIFormNodePThis node defines the namespaces for the function. Use null if the node that this function is operating on has inherited the necessary namespaces.
theFilenameStringThe 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.
theMemoryBlockVariantThe memory block that contains the instance data. Use nothing if you are reading from a file, input stream, or Reader.
updateTypeLongOne 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 XFormsModelUpdate 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.


Nothing if the call is successful. Throws an exception if an error occurs.


Modifying the XForms data model
The UpdateXFormsInstance function and the ExtractXFormsInstance 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, UpdateXFormsInstance performs its default behavior. However, this default behavior varies depending on how the form is loaded:
  • If the form is opened without using the ReadForm function, or the form is loaded using the ReadForm function but the flags parameter is set to 0, then UpdateXFormsInstance automatically updates the data model each time that a change is made to the model.
  • If the form is loaded using the ReadForm function with the flags parameter set to UFL_SERVER_SPEED_FLAGS_WITH_XFORMS or UFL_XFORMS_INITIALIZE_ONLY, then UpdateXFormsInstance marks the data model for a later update when a change is made to the model. To enact this update, use the XFormsModelUpdate function.
  • If the form is loaded using the ReadForm function with the flags parameter set to UFL_SERVER_SPEED_FLAGS, then UpdateXFormsInstance 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 UpdateXFormsInstance 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 UpdateXFormsInstance 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 routine that you can use to replace it.
Instance data:
   <xforms:instance id="instance1" xmlns="">

   Sub SaveDataInstance(Form)
      Form.UpdateXFormsInstance "model1",
          Nothing, "c:\InstanceData.xml", Nothing, XFORMS_UPDATE_REPLACE)
   End Sub

Parent topic:
FormNodeP functions