Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## Writing XML from a temp-table, temp-table buffer, or ProDataSet

> The `WRITE-XML()` method writes an XML document containing the data for a temp-table, temp-table buffer, or ProDataSet object. 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, Progress 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 for each table row are written.

> When writing XML Schema for a ProDataSet object, Progress writes all table definitions as well as relation and index definitions. When writing schema for a temp-table or temp-table buffer object, Progress writes table and index definitions.

> Here is the syntax for `WRITE-XML( )`. The method returns `TRUE` or `FALSE` to indicate whether the operation was successful.

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

> ``target-type``

> 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 Progress 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, Progress 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 (""), Progress 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, Progress deletes the existing text first.

> ``longchar``

> A `LONGCHAR` variable to contain the XML document text.

> Progress 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, Progress 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 Progress 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 Progress 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 Progress XML Parser. For a list of supported IANA encodings and their corresponding Progress code pages, see Appendix D "XML Reference of Data Type and Code Page mappings.".

> Note: Progress records this character encoding in the encoding declaration in the XML document’s prologue. If you specify the empty string ("") or the Unknown value (`?`), Progress uses the default encoding of `UTF-8`. In this case, Progress 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.

> 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 Progress to write the ProDataSet or temp-table object’s definition as in-line XML Schema along with the data, and `FALSE` directs Progress 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 Progress to write the minimum amount of schema when it writes the XML Schema representation of the object, and `FALSE` directs Progress to write the complete schema including Progress-specific XML Schema attributes. The default value is `FALSE`. If you specify the Unknown value (`?`), the method uses the default value of `FALSE`.

> When `TRUE`, Progress-specific XML Schema information is omitted from the XML Schema. For a complete list of progress XML Schema extensions, see "Using XML Schema" section. If the Progress data type of the temp-table field is not the default Progress data type for the XML Schema type, Progress 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), Progress writes the `prodata:initial` XML Schema attribute for the field.

> ``write-before-image``

> An optional `LOGICAL` expression where `TRUE` directs Progress to write any before-image table data and error information in addition to the ProDataSet object data, and `FALSE` directs Progress 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`.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095