Writing XML from a temp-table, temp-table buffers, or a ProDataSet
The WRITE-XML( ) method writes an XML document containing the data of a temp-table or ProDataSet object. The method can be used on a temp-table buffer, but here it writes the entire contents of the associated temp-table, not just the contents of the buffer. You can optionally write the definition of the object along with the data. If you include the object's definition, 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 tle in the ProDataSet object. However, you can also include any before-image data, so that both the current and original versions of the data for each table row are written.
When writing XML Schema for a ProDataSet object, the AVM writes all table definitions as well as relation and index definitions. When writing XML Schema for a temp-table or temp-table buffer object, the AVM writes table and index definitions.
Here is the syntax for WRITE-XML( ). The method returns TRUE or FALSE to indicate if the operation was successful.
A CHARACTER expression that specifies the target XML document type. Valid values are: "FILE", "STREAM", "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 writable 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.
memptr
A MEMPTR variable to contain the XML document text. 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.
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 function) 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 ABLto IANA Code Page Mappings.
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 to UTF-8.
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.
Note: You must provide the location of an actual XML Schema document. Consider using the WRITE-XMLSCHEMA( ) method to generate the XML Schema document.
write-xmlschema
An optional LOGICAL expression where TRUE directs the AVM to write the ProDataSet or temp-table object's definition as in-line XML Schema along with the data, and FALSE directs the AVM to write only the data. The default value is 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 the AVM-specific XML Schema extensions. The default value is FALSE. If you specify the Unknown value (?), the method uses the default value of FALSE.
When TRUE, most ABL-specific XML Schema information is omitted from the XML Schema. For a complete list of ABL XML Schema extensions, see Using 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.
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.
Note: For an array field to be omitted, each element of the array must contain the initial value.
