WRITE-XMLSCHEMA( ) method

Writes an XML representation of the definition of a ProDataSet, temp-table, or temp-table buffer object (that is, an XML Schema file). The XML Schema is written using the XML Schema Definition (XSD) language.

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-XMLSCHEMA ( target-type 
  , { file | stream | stream-handle | memptr | handle | longchar }
  [ , formatted [ , encoding [ , min-xmlschema [ , omit-initial-values 
  ] ] ] ] )

target-type

A CHARACTER expression that specifies the target XML Schema 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 Schema 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. The pathname can contain Unicode characters. See OpenEdge Development: Internationalizing Applications for more information about Unicode.

stream

A CHARACTER expression that specifies the name of a stream. If you specify the empty string (""), the AVM writes the XML Schema document text to the default unnamed output stream. For WebSpeed, write the XML Schema 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 CHARACTER expression that specifies a stream object handle.

memptr

A MEMPTR variable to contain the XML Schema 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 Schema document text in memory.

The AVM saves the XML Schema 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 Schema 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-XMLSCHEMA( ) method returns an error and the XML Schema document is not saved to the LONGCHAR.

formatted

An optional LOGICAL expression where TRUE directs the AVM to format the XML Schema 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 Schema 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 1 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.

min-xmlschema

An optional LOGICAL expression where TRUE directs the AVM to write the minimum amount of schema for 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.

omit-initial-values

An optional LOGICAL expression where TRUE directs the AVM to indicate in the XML Schema that the fields are optional in the XML instance document, and FALSE directs the AVM to indicate in the XML Schema that the fields are required in the XML instance document. The default value is FALSE. If you specify the Unknown value (?), the method uses the default value of FALSE.

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.

Note: See the entry in WRITE-XML( ) method for this argument for considerations of using this argument with XML data.

If the NAMESPACE-URI attribute value for a temp-table 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 you specify multiple namespaces and target-type is not "FILE", the method generates an error and returns FALSE.

You can specify how a temp-table column is represented in XML Schema (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 schema for a ProDataSet object that contains data-relations, you can nest child rows of a ProDataSet buffer definition within their parent buffer definitions in the resulting XML Schema 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
• Specifying the FOREIGN-KEY-HIDDEN option to prevent duplicating the key fields in the child records that are nested within the parent record

If your temp-tables contain array fields, third party products utilizing the XML Schema 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 representation of the schema for a database buffer.

The following code example defines a static ProDataSet object and writes the ProDataSet object schema to an XML Schema file:

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

ASSIGN
  cTargetType = "file"
  cFile       = "cust-ord-inv.xsd" 
  lFormatted  = TRUE
  cEncoding   = ?
  lMinSchema  = FALSE.

lRetOK = DATASET DSET:WRITE-XMLSCHEMA(cTargetType, cFile, lFormatted,
  cEncoding, lMinSchema).

The following code example defines a static temp-table object, and writes the temp-table object schema to an XML Schema file:

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 lMinSchema  AS LOGICAL   NO-UNDO.
DEFINE VARIABLE lRetOK      AS LOGICAL   NO-UNDO.

DEFINE TEMP-TABLE ttCust NO-UNDO LIKE Customer.

ASSIGN
  cTargetType = "file"
  cFile       = "ttCust.xsd" 
  lFormatted  = TRUE
  cEncoding   = ?
  lMinSchema  = FALSE.

lRetOK = TEMP-TABLE ttCust:WRITE-XMLSCHEMA(cTargetType, cFile, lFormatted,
  cEncoding, 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, WRITE-XML( ) method, XML-NODE-TYPE attribute