Community articleUFLExtractXFormsInstance 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.


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.


   r_short UFLExtractXFormsInstance(
      formNodeP theObject,
      r_charP theModelID,
      r_charP theNodeRef,
      r_short writeRelevant,
      r_short ignoreFailures,
      formNodeP theNSNode,
      r_charP theFilename,
      r_byte **returnPtr,
      r_long *returnSizePtr


Table 1. Function parameters
theObject formNodePThe formNodeP object.
theModelIDr_charPThe ID of the model to extract. Use NULL to extract the default model.
theNodeRefr_charPAn XPath reference to a node in the instance. This node and all of its children are copied. Leave blank to extract the entire instance.
writeRelevantr_shortIf OK, writes only relevant instance data, else use NOTOK.
ignoreFailuresr_shortIf OK, ignores constraint or validation failures, else use NOTOK.
theNSNodeformNodePA 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.
theFilenamer_charPThe name and path of the file to write to. Use NULL to write to the output memory block.
returnPtr r_byte**A pointer that is set with the memory block that represents the instance.
returnSizePtr r_long*A pointer to the size of the memory block.


OK on success or an error code on failure.


XForms data model
The UFLUpdateXFormsInstance and the UFLExtractXFormsInstance functions are the only functions that are intended to modify the XForms data model.
Using UFLExtractXFormsInstance with UFLReadForm
If a form is read with XForms processing off, you must set the writeRelevant parameter to NOTOK and the ignoreFailures parameter to OK.
Note: Extracting an XForms instance to a file
When extracting an XForms instance to a file, you must still declare returnPtr and returnSizePtr even though they are not used.


The following example shows an XForms instance and a function 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="">

  r_error updateDataInstance(formNodeP theForm)
     r_byte *theBuffer = NULL; 
     r_long theBufferSize = 0;
     if (UFLExtractXFormsInstance(theForm, "model1", 
        NOTOK, OK, NULL, 
        "C:\\Instance Files\\Personnel\\InstanceData.xml", 
        &theBuffer, &theBufferSize) != OK)
        fprintf(stderr, "Could not extract data instance.");

Parent topic:
FormNodeP functions