xml.Serializer.OptimizedVariableToDom

Serializes a BDL variable into a XML element node using a DomNode object.

This API implements the XML-binary Optimized packaging specification. See https://www.w3.org/TR/xop10/.

Syntax

xml.Serializer.OptimizedVariableToDom(
   var fgl-type,
   node xml.DomNode,
   xopTable RECORD )
  1. var is any Genero BDL data type. Or it can be a structured type, like a RECORD or ARRAY, including elements with these data types. Optional XML mapping attributes can be added to the definition of variables for XML serialization.
  2. node is a DomNode object of type ELEMENT_NODE or DOCUMENT_FRAGMENT_NODE.
  3. xopTable is a dynamic array, defined as follows:
    DEFINE XOPTable DYNAMIC ARRAY OF RECORD
      cid STRING, # Content-ID to identify the part in a XML Optimized document
      data BYTE,  # Blob handled as part in a XML Optimized document
      file STRING # Name of the file handled as part in an XML Optimized document
    END RECORD
    The XOPtable dynamic array is necessary to keep the relation between the data to be handled as separate part in an XML Optimized document via an href attribute containing the Content-ID value. This parameter can be NULL.

Usage

The resulting XML element node of the serialization process will be added at the current cursor position of the StaxWriter object.

In case of error, the method throws an exception and sets the status variable. Depending on the error, a human-readable description of the problem is available in the sqlca.sqlerrm register. See Error handling in GWS calls (status).

Optimized APIs

Optimized APIs work in the same method as the non-Optimized APIs, with the addition that the optimized API supports XML-binary Optimized format, and return in the XOPTable (if not NULL) the BYTE or the file on disk to handle as a separate part based on the Content-ID.

For instance, if a BYTE has to be sent as an attachment via MTOM, the API will create an XML Optimized node with an href containing the Content-ID returned in the XOP table. This node will include a reference to that BYTE.

For example, given this example of an XML-optimized document:
<m:data xmlns:m='http://example.org/stuff'>
  <m:photo>
  <xop:Include xmlns:xop='http://www.w3.org/2004/08/xop/include' 
  href='cid:myref@tempuri.org'/>
  </m:photo>
</m:data>
If you have NOT used XMLOptimizedContent, the XOPTable will contain one element where:
  • cid contains "myref@tempuri.org".
  • data contains the BYTE to be sent or to be received as an attachment.
  • file contains NULL.
If you have used XMLOptimizedContent, the XOPtable contains one element where:
  • cid contains "myref@tempuri.org".
  • data contains NULL.
  • file contains the filename to be sent or to be received as an attachment..