Community articleExtractXFormsInstance 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 copies an entire XForms instance or a portion of an XForms instance to a file or a memory block. This function does not remove the instance from the form.
Call this function on the root node of the form or an instance node.


   Sub ExtractXformsInstance(
      theModelID As String, 
      theNodeRef As String, 
      writeRelevant As Boolean, 
      IgnoreFailures As Boolean, 
      theNSNode As IFormNodeP, 
      theFilename As String, 
      theMemoryBlock As Variant)


Table 1. Function parameters
theModelIDStringThe ID of the model to extract. Use vbnullstring to extract the default model.
theNodeRefStringAn XPath reference to a node in the instance. This node and all of its children are copied. Leave blank to extract the entire instance.
writeRelevantBooleanIf True, writes only relevant instance data, else use False.
ignoreFailuresBooleanIf True, ignores constraint or validation failures, else use False.
theNSNodeIFormNodePA node that inherits the namespaces used in the reference. This node defines the namespaces for the function. Use null if the node that this function is operating on has inherited the necessary namespaces.
theFilenameStringThe name and path of the file to write to. Use vbnullstring to write to the output memory block.
theMemoryBlock VariantThe memory block that represents the instance if you are not writing to a file.


Nothing if call is successful or throws an exception if an error occurs.

Usage details

XForms data model
The UpdateXFormsInstance and the ExtractXFormsInstance functions are the only functions that are intended to modify the XForms data model.
Using ExtractXFormsInstance with ReadForm
If a form is read with XForms processing off, you must set the writeRelevant parameter to False and the ignoreFailures parameter to True.


The following example shows an XForms instance and a routine that takes the root node of a form, extracts an XForms instance, and writes it to a file called "InstanceData.xml".
Instance data:
   <xforms:instance id="instance1" xmlns="">

   Sub SaveDataInstance(Form)
         "instance('instance1')/loanrecord.user_personal_info", True, False,
          Nothing, "c:\InstanceData.xml", Nothing
   End Sub

Parent topic:
FormNodeP functions