WRITE-XML( ) method

Writes an XML document from a ProDataSet, temp-table, or temp-table buffer object. In the case of the temp-table buffer object, all the records of the temp-table associated with the buffer object are written to the XML document—not just the one in the buffer. You can write the XML representation of the object with data, schema, or both. If you include schema, it is written using the XML Schema Definition (XSD) language.

When writing data from a ProDataSet object, the AVM writes the current version of data in each row of each table in the ProDataSet object. However, you can also include any before-image data, so that both the current and original versions of the data in each table row are written.

When writing schema for a ProDataSet object, the AVM writes all table definitions as well as relation and index definitions. When writing schema for a temp-table or temp-table buffer object, the AVM writes only table and index definitions.

Return type:

LOGICAL

Applies to:

Buffer object handle, ProDataSet object handle, Temp-table object handle

 

Syntax 

WRITE-XML ( target-type   , { file | stream | stream-handle | memptr | handle | longchar }   [ , formatted [ , encoding [ , schema-location [ , write-xmlschema   [ , min-xmlschema [ , write-before-image [ , omit-initial-values   ] ] ] ] ] ] ] )

target-type

A CHARACTER expression that specifies the target XML document type. Valid values are: "FILE", "STREAM", "STREAM-HANDLE", "MEMPTR", "HANDLE", and "LONGCHAR".

file

A CHARACTER expression that specifies the name of a file to which the AVM writes the XML document text. You can specify an absolute pathname or a relative pathname (based on the current working directory). If a file with the specified name already exists, the AVM verifies that the file is writeable and overwrites the file.

stream

A CHARACTER expression that specifies the name of a stream. If you specify the empty string (""), the AVM writes the XML document text to the default unnamed output stream. For WebSpeed, write the XML document text to the WebSpeed-defined output stream (WEBSTREAM).

For more information about using ABL unnamed output streams, see the DEFINE STREAM statement reference entry and the chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces. For more information about using WebSpeed-defined output streams, see OpenEdge Application Server: Developing WebSpeed Applications.

stream-handle

A HANDLE variable that specifies a stream object handle.

memptr

A MEMPTR variable to contain the XML document text in memory. The method allocates the required amount of memory for the XML document text and sets the size of the variable. When you are finished using the MEMPTR, you must free the associated memory by executing SET-SIZE(memptr) = 0 on the MEMPTR.

handle

An X-document object handle or X-noderef object handle. If the specified handle contains XML text, the AVM deletes the existing text first.

longchar

A LONGCHAR variable to contain the XML document text in memory.

The AVM saves the XML document text to the LONGCHAR variable in the code page that corresponds to the character encoding you specify in the encoding option. If you do not specify a character encoding for the XML document text, the AVM saves the LONGCHAR variable in UTF-8.

If the LONGCHAR variable’s code page is fixed (that is, set using the FIX-CODEPAGE statement) and the fixed code page is not equivalent to the character encoding you specify in the encoding option, the WRITE-XML( ) method returns an error and the XML document is not saved to the LONGCHAR.

formatted

An optional LOGICAL expression where TRUE directs the AVM to format the XML document text in a hierarchical manner using extra white space, carriage returns, and line feeds. The default value is FALSE.

If you specify the Unknown value (?), the method uses the default value of FALSE.

encoding

An optional CHARACTER expression that specifies the name of the character encoding the AVM uses to write the XML document text. The default encoding is UTF-8.

The encoding name must be an Internet Assigned Numbers Authority (IANA) name supported by the ABL XML Parser. For a list of supported IANA encodings and their corresponding ABL code pages, see Table 77 in the ENCODING attribute reference entry.

Note:

The AVM records this character encoding in the encoding declaration in the XML document’s prologue. If you specify the empty string ("") or the Unknown value (?), the AVM uses the default encoding of UTF-8. In this case, the AVM does not record the character encoding in the XML document’s encoding declaration.

If target-type is "HANDLE", the X-document’s ENCODING attribute is also set.

schema-location

An optional CHARACTER expression that specifies the name of an external XML Schema file. The method uses this value to set the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute in the XML document. If the ProDataSet or temp-table object’s NAMESPACE-URI attribute is the empty string ("") or the Unknown value (?), the method adds the xsi:noNamespaceSchemaLocation attribute in the XML document and sets it to this value. If the NAMESPACE-URI attribute is not the empty string ("") or the Unknown value (?), the method adds the xsi:schemaLocation attribute to the XML document with a value of "namespace-uri<space>schema-location". The default value is the Unknown value (?).

Note:

You must provide the location of an actual XML Schema file. Consider using the WRITE-XMLSCHEMA( ) method to generate the XML Schema file.

If you specify write-xmlschema as TRUE, you cannot specify schema-location.

write-xmlschema

An optional LOGICAL expression where TRUE directs the AVM to write the ProDataSet or temp-table object’s relational structure as in-line XML Schema along with the data, and FALSE directs the AVM to write only the data. The default value is FALSE.

If you specify TRUE, you cannot specify schema-location. If you specify FALSE, you must also specify min-xmlschema as FALSE. If you specify the Unknown value (?), the method uses the default value of FALSE.

Note:

If you specify TRUE and the NAMESPACE-URI attribute value for a temp-table buffer within a ProDataSet object is different than that of the ProDataSet object, the method creates a separate XML Schema file for the temp-table definition. The namespace URI for the temp-table is imported into the ProDataSet schema, with a schemaLocation pointing to a separate XML Schema file containing the temp-table definition. Multiple namespaces are supported only when target-type is "FILE". If the ProDataSet object contains multiple namespaces and target-type is not "FILE", the method generates an error and returns FALSE.

min-xmlschema

An optional LOGICAL expression where TRUE directs the AVM to write the minimum amount of schema when it writes the XML Schema representation of the object, and FALSE directs the AVM to write the complete schema including ABL-specific schema attributes. The default value is FALSE. If you specify the Unknown value (?), the method uses the default value of FALSE.

When TRUE, ABL-specific schema information (such as, field format, non-unique indexes, and so on) is omitted from the XML Schema. If the ABL data type of the temp-table field is not the default ABL data type for the XML Schema type, the AVM writes the prodata:dataType XML Schema attribute for the field. If the initial value of the temp-table field is TODAY, NOW, or UNKNOWN (and UNKNOWN is not the default initial value for the field’s data type), the AVM writes the prodata:initial XML Schema attribute for the field.

When TRUE, the XML Schema will contain any ABL-specific XML Schema attributes needed to define the data relations for a ProDataSet.

If you specify write-xmlschema as FALSE, you must also specify min-xmlschema as FALSE.

write-before-image

An optional LOGICAL expression where TRUE directs the AVM to write any before-image table data and error information in addition to the ProDataSet object data, and FALSE directs the AVM to write only the ProDataSet object data. The default value is FALSE. If you specify the Unknown value (?), the method uses the default value of FALSE.

omit-initial-values

An optional LOGICAL expression where TRUE directs the AVM to exclude temp-table fields containing their initial values from the XML document, and FALSE directs the AVM to include all temp-table field data in the XML. The default value is FALSE. If you specify the Unknown value (?), the method uses the default value of FALSE.

When working with large ProDataSets, omitting initial values in records can yield smaller XML documents, more efficient network transfers, and performance gains with the READ-XML( ) and WRITE-XML( ) methods.

The XML Schema indicates what the initial values for the omitted temp-table fields are, thus ensuring round trip of the XML data from and to OpenEdge applications. The READ-XML( ) method assigns the field its initial value when the field is not present in the XML document.

This behavior applies both to temp-table fields that have the default initial value for its data type and for fields that have an initial value set with the ABL INITIAL option.

Although using the omit-initial-values option can give your application performance and resource use improvements, you need to be sure that the consumers of the generated XML document will correctly handle the XML. The ABL READ-XML( ) method will always populate created records with initial values from the temp-table or ProDataSet definition. Other applications might not do this.

For example, .NET can read an XML Schema and XML data document into a dynamic ADO .NET DataSet using its ReadXmlSchema( ) and ReadXml( ) APIs, but missing elements are always interpreted as a null (the Unknown value (?) in ABL terms) DataColumn in the DataTable. They do recognize the initial value definition in the XML Schema when creating rows in the DataTable directly (initial value in the XML Schema gets translated to the DefaultValue property on the DataColumn), but do not with ReadXml( ).

Note:

For an array field to be omitted, each element of the array must contain the initial value.

You can specify how a temp-table column is represented in XML (that is, as an ELEMENT, ATTRIBUTE, or TEXT) by:

Setting the XML-NODE-TYPE attribute on the Buffer-field object handle

Specifying the XML-NODE-TYPE option on the DEFINE TEMP-TABLE statement

When writing data from a ProDataSet object that contains data-relations, you can nest child rows of a ProDataSet buffer within their parent rows in the resulting XML document by:

Setting the NESTED attribute on the data-relation object handle to TRUE

Specifying the NESTED option for the data-relation on the DEFINE DATASET statement

Specifying the NESTED option in the ADD-RELATION( ) method

Specify a PARENT-ID-RELATION in the DEFINE DATASET statement

Using the ADD-PARENT-ID-RELATION( ) method on a dynamic ProDataSet object

ABL has pairs of attributes with overlapping purposes in how the AVM outputs XML data:

SERIALIZE-HIDDEN and XML-NODE-TYPE

SERIALIZE-NAME and XML-NODE-NAME

Refer to the attribute entries for a full description of their interaction.

If your temp-tables contain array fields, third party products utilizing the XML might not map the ABL array field to an array column or object. For best interoperability with third party products, flatten array fields into individual fields.

You cannot write an XML document from a database buffer.

Note:

When executing the WRITE-XML( ) method on a temp-table or ProDataSet, and the default buffer of one of the contained temp-tables is available, there is no guarantee as to the state of that buffer after the method finishes executing. The record buffer may not be available. If default buffer availability is an issue, it is suggested that a named buffer be used with this method. A named buffer can be created with the DEFINE BUFFER statement.

The following code example defines a static ProDataSet object, attaches its data sources, fills the ProDataSet object, and writes the ProDataSet object to an XML document in a nested manner:

 

DEFINE VARIABLE cTargetType     AS CHARACTER NO-UNDO. DEFINE VARIABLE cFile           AS CHARACTER NO-UNDO. DEFINE VARIABLE lFormatted      AS LOGICAL   NO-UNDO. DEFINE VARIABLE cEncoding       AS CHARACTER NO-UNDO. DEFINE VARIABLE cSchemaLocation AS CHARACTER NO-UNDO. DEFINE VARIABLE lWriteSchema    AS LOGICAL   NO-UNDO. DEFINE VARIABLE lMinSchema      AS LOGICAL   NO-UNDO. DEFINE VARIABLE lRetOK          AS LOGICAL   NO-UNDO.   DEFINE TEMP-TABLE ttCustomer NO-UNDO LIKE Customer. DEFINE TEMP-TABLE ttOrder    NO-UNDO LIKE Order. DEFINE TEMP-TABLE ttInvoice  NO-UNDO LIKE Invoice.   DEFINE DATASET DSET FOR ttCustomer, ttOrder, ttInvoice   DATA-RELATION CustOrd FOR ttCustomer,     ttOrd RELATION-FIELDS(CustNum,CustNum) NESTED   DATA-RELATION OrdInv FOR ttOrder,     ttInv RELATION-FIELDS(OrderNum,OrderNum) NESTED.   DEFINE DATA-SOURCE dsCustomer FOR Customer. DEFINE DATA-SOURCE dsOrder    FOR Order. DEFINE DATA-SOURCE dsInvoice  FOR Invoice.   BUFFER ttCustomer:HANDLE:ATTACH-DATA-SOURCE(DATA-SOURCE dsCustomer:HANDLE). BUFFER ttOrder:HANDLE:ATTACH-DATA-SOURCE(DATA-SOURCE dsOrder:HANDLE). BUFFER ttInvoice:HANDLE:ATTACH-DATA-SOURCE(DATA-SOURCE dsInvoice:HANDLE).   DATA-SOURCE dsCustomer:FILL-WHERE-STRING = "WHERE Customer.CustNum = 2 ". DATASET DSET:FILL().   ASSIGN   cTargetType     = "file"   cFile           = "dset.xml"   lFormatted      = TRUE   cEncoding       = ?   cSchemaLocation = ?   lWriteSchema    = FALSE   lMinSchema      = FALSE.   lRetOK = DATASET DSET:WRITE-XML(cTargetType, cFile, lFormatted, cEncoding,   cSchemaLocation, lWriteSchema, lMinSchema).

The following code example defines a static temp-table object, populates the temp-table object (code not shown), and writes the temp-table object to an XML document:

 

DEFINE VARIABLE cTargetType     AS CHARACTER NO-UNDO. DEFINE VARIABLE cFile           AS CHARACTER NO-UNDO. DEFINE VARIABLE lFormatted      AS LOGICAL   NO-UNDO. DEFINE VARIABLE cEncoding       AS CHARACTER NO-UNDO. DEFINE VARIABLE cSchemaLocation AS CHARACTER NO-UNDO. DEFINE VARIABLE lWriteSchema    AS LOGICAL   NO-UNDO. DEFINE VARIABLE lMinSchema      AS LOGICAL   NO-UNDO. DEFINE VARIABLE lRetOK          AS LOGICAL   NO-UNDO.   DEFINE TEMP-TABLE ttCust NO-UNDO LIKE Customer.   /* Code to populate the temp-table */ ASSIGN   cTargetType     = "file"   cFile           = "ttCust.xml"   lFormatted      = TRUE   cEncoding       = ?   cSchemaLocation = ?   lWriteSchema    = FALSE   lMinSchema      = FALSE.   lRetOK = TEMP-TABLE ttCust:WRITE-XML(cTargetType, cFile,lFormatted, cEncoding,   cSchemaLocation, lWriteSchema, lMinSchema).

See also:

ENCODING attribute, FIX-CODEPAGE statement, FOREIGN-KEY-HIDDEN attribute, NAMESPACE-PREFIX attribute, NAMESPACE-URI attribute, NESTED attribute, READ-XML( ) method, READ-XMLSCHEMA( ) method, SERIALIZE-ROW( ) method, SERIALIZE-HIDDEN attribute, SERIALIZE-NAME attribute, SERIALIZE-ROW( ) method, WRITE-XMLSCHEMA( ) method, XML-NODE-NAME attribute, XML-NODE-TYPE attribute