READ-XMLSCHEMA( ) method

Reads XML Schema from an XML document and uses that schema to either create a schema for a ProDataSet or temp-table object, or verify existing schema in a ProDataSet, temp-table, or temp-table buffer object.

Return type: LOGICAL

Applies to: Buffer object handle, ProDataSet object handle, Temp-table object handle

Syntax

READ-XMLSCHEMA ( source-type 
  , { file | memptr | handle | longchar } 
  , override-default-mapping 
  [ , field-type-mapping [ , verify-schema-mode ] ] )

source-type

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

file

A CHARACTER expression that specifies the name of an XML Schema file. You can specify an absolute pathname, a relative pathname (based on the current working directory), or a URL pathname. Valid URL protocols include FILE and HTTP (the HTTPS protocol is not supported). The AVM verifies that the file exists and is accessible. The pathname can contain Unicode characters. See OpenEdge Development: Internationalizing Applications for more information about Unicode.

memptr

A MEMPTR variable that contains the XML Schema document text. The size of the MEMPTR variable must match the size of the XML document text.

handle

A WEB-CONTEXT system handle, X-document object handle, or X-noderef object handle.

For a WEB-CONTEXT system handle, the READ-XMLSCHEMA( ) method reads an XML Schema document from the WebSpeed transaction server. The method verifies that the XML document was posted to the WebSpeed transaction server (that is, the value of the IS-XML attribute for the handle is YES), and that ABL is running in a WebSpeed environment.

longchar

A LONGCHAR variable that contains the XML Schema document text in memory.

override-default-mapping

A LOGICAL expression where TRUE directs the AVM to override the default mapping between XML Schema string and binary data types and ABL data types when creating an ABL temp-table schema from an XML Schema. The default value is FALSE.

The XML Schema string data type maps to the ABL CHARACTER data type by default, and the XML Schema base64Binary and hexBinary data types map to the ABL RAW data type by default. If you specify TRUE, the READ-XMLSCHEMA( ) method creates a temp-table schema with CLOB and BLOB fields instead of CHARACTER and RAW fields.

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

field-type-mapping

An optional CHARACTER expression that evaluates to a comma-delimited list of field name, data type pairs using the following syntax:

"field-name-1,data-type-1[,field-name-n,data-type-n]..."

This option allows you to specify the ABL data type for a specific field from the XML Schema.

field-name

A CHARACTER expression that evaluates to the name of the specified field. For a ProDataSet object, you must qualify the field name with the buffer name from the XML Schema. That is, buffer-name.field-name.

data-type

A CHARACTER expression that evaluates to the data type of the specified field. The data type must be a valid ABL data type, and it must be compatible with the XML Schema type based on the ABL XML data type mapping rules. For example, any XML Schema type can be mapped to an ABL CHARACTER or CLOB, but an XML Schema dateTime can be mapped only to an ABL DATE, DATETIME or DATETIME-TZ.

If you specify the Unknown value (?), the method uses the default data type. For more information about the ABL XML data type mapping rules, see OpenEdge Development: Working with XML.

verify-schema-mode

An optional CHARACTER expression that specifies the mode in which the READ-XMLSCHEMA( ) method verifies any XML Schema against existing ABL schema. The expression must evaluate to "LOOSE" or "STRICT". The default value is "LOOSE".

Note: For a dynamic temp-table or ProDataSet member buffer that does not have ABL schema (that is, the object is in the CLEAR state), this option is ignored.

The following table lists the READ-XMLSCHEMA( ) method schema verification modes.

READ-XMLSCHEMA( ) method verification modes

When the mode is . . .	The READ-XMLSCHEMA( ) method . . .
LOOSE for temp-table objects	Matches temp-table columns by name. The data type and extent of the column in the XML Schema must match those for the matching column in the temp-table. Other field attributes in the XML Schema are ignored. The XML Schema may be a subset or superset of the temp-table schema. Any columns that are in the XML Schema but not in the temp-table are ignored. Any columns that are in the temp-table, but not in the XML Schema, are ignored.
LOOSE for ProDataSet objects	Matches temp-tables and columns by name. The data type and extent of the column in the XML Schema must match those for the matching column in the temp-table. Other field attributes in the XML Schema are ignored. Data relationships are matched by parent buffer and child buffer names. For every data relationship in the XML Schema that matches a data-relation in the ProDataSet, the field mapping between the parent and child buffers must match. The XML Schema may be a subset or superset of the ProDataSet schema. Any temp-tables, columns, or data-relations that are in the ProDataSet, but not in the XML Schema, are ignored. For a dynamic ProDataSet object, the method adds temp-tables and data-relations to the object when the temp-tables and data-relations are defined in the XML Schema, but are not members of the ProDataSet. Fields are not added to existing temp-tables. For a static ProDataSet object, any temp-tables or data-relations that are in the XML Schema, but not in the ProDataSet, are ignored.
STRICT for temp-table objects	Matches temp-table columns by name. The data type and extent of the column in the XML Schema must match those for the matching column in the temp-table. Other field attributes in the XML Schema are ignored. The XML Schema must define a field for every temp-table field, and there can be no extra fields in the XML Schema that are not in the temp-table schema.
STRICT for ProDataSet objects	Matches temp-tables and columns by name. There must be a temp-table defined in the XML Schema for each table of the ProDataSet. There can be no tables defined in the XML Schema that are not in the ProDataSet schema. There must be field defined in the XML Schema for each field in the temp-table, with the same data type and extent, and there can be no fields defined in the XML Schema that are not in the temp-table schema. There must also be a data relationship defined in the XML Schema for every data-relation in the ProDataSet, and there can be no data relationships defined in the XML Schema that are not defined in the ProDataSet. The field mapping between the parent and child buffers must match.

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

If the XML Schema verification fails, the method generates an error message indicating the XML Schema element that caused the failure and returns FALSE.

If the ProDataSet or temp-table object does not have a schema (that is, the object is dynamic and in the CLEAR state), the AVM creates the schema from the XML Schema defined in the XML Schema document.

If the ProDataSet or temp-table object already has a schema (that is, the object is static, or the temp-tables are in the PREPARED state), the AVM verifies the XML Schema defined in the XML Schema document against the object's schema.

If a dynamic temp-table is not in the PREPARED or CLEAR state, the method generates an error and returns FALSE.

For more information about creating schema from XML Schema or verifying XML Schema, see OpenEdge^® Development: Working with XML.

You cannot create schema for a temp-table buffer or a database buffer.

The following code example verifies the schema in a static ProDataSet object, in STRICT mode, using the schema defined in the specified XML Schema file:

DEFINE VARIABLE lRetOK                  AS LOGICAL   NO-UNDO.
DEFINE VARIABLE cSourceType             AS CHARACTER NO-UNDO.
DEFINE VARIABLE cFile                   AS CHARACTER NO-UNDO.
DEFINE VARIABLE lOverrideDefaultMapping AS LOGICAL   NO-UNDO.
DEFINE VARIABLE cFieldTypeMapping       AS CHARACTER NO-UNDO.
DEFINE VARIABLE cVerifySchemaMode       AS CHARACTER NO-UNDO.

DEFINE TEMP-TABLE ttCustomer LIKE Customer NO-UNDO.
DEFINE TEMP-TABLE ttOrder    LIKE Order    NO-UNDO.
DEFINE TEMP-TABLE ttInvoive  LIKE Invoice  NO-UNDO.

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
  cSourceType             = "file"
  cFile                   = "cust-ord-inv.xsd"
  lOverrideDefaultMapping = FALSE
  cFieldTypeMapping       = ?
  cVerifySchemaMode       = "strict".

lRetOK = DATASET DSET:READ-XMLSCHEMA (cSourceType, cFile,
  lOverrideDefaultMapping, cFieldTypeMapping,cVerifySchemaMode).

The following code example creates a dynamic temp-table object, creates the object's schema from the specified XML Schema file, and overrides the default data type mapping of one field:

DEFINE VARIABLE lRetOK                  AS LOGICAL   NO-UNDO.
DEFINE VARIABLE cSourceType             AS CHARACTER NO-UNDO.
DEFINE VARIABLE cFile                   AS CHARACTER NO-UNDO.
DEFINE VARIABLE lOverrideDefaultMapping AS LOGICAL   NO-UNDO.
DEFINE VARIABLE cFieldTypeMapping       AS CHARACTER NO-UNDO.
DEFINE VARIABLE cVerifySchemaMode       AS CHARACTER NO-UNDO.
DEFINE VARIABLE hTable                  AS HANDLE    NO-UNDO.

CREATE TEMP-TABLE hTable.
ASSIGN
  cSourceType             = "file"
  cFile                   = "ttcust.xsd"
  lOverrideDefaultMapping = FALSE
  cFieldTypeMapping       = "address2,CLOB"
  cVerifySchemaMode       = ?.

lRetOK = hTable:READ-XMLSCHEMA (cSourceType, cFile, lOverrideDefaultMapping,
  cFieldTypeMapping,cVerifySchemaMode).

See also

IS-XML attribute, READ-XML( ) method, WEB-CONTEXT system handle, WRITE-XML( ) method, WRITE-XMLSCHEMA( ) method, SERIALIZE-ROW( ) method, X-document object handle, X-noderef object handle