Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## Reading XML Schema into a temp-table, temp-table buffer, or ProDataSet

> `Reading XML Schema using` `READ-XMLSCHEMA( )``has two distinct meanings, depending on your use case:`

> - `If you are creating a dynamic object, then reading XML Schema is the process of creating the definition of the dynamic object from the specified XML Schema.`

> - If the object already has a definition, then reading XML Schema is the process of comparing the existing definition to the specified XML Schema. This comparison is known as verification. Since static objects cannot exist without a definition, the purpose of reading XML Schema into a static object is always verification. If a dynamic object already has its definition, then the purpose of reading XML Schema into it is also verification.

> Verification allows you to test the compatibility of the object with the specified XML Schema document. If the object and XML Schema are not an exact or close match, the `READ-XMLSCHEMA( )` method call fails and returns `FALSE`. The `verification-mode` parameter (described later) controls how close the match must be.

> Note: The XML document must be an XML Schema written in the XML Schema Definition (XSD) language in the 2001 XML Schema namespace (http://www.w3.org/2001/XMLSchema).

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

> 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). Progress verifies that the file exists and is accessible.

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

> ``longchar``

> A `LONGCHAR` variable that contains the XML Schema document text.

> ``override-default-mapping``

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

> The XML Schema string data type maps to the Progress `CHARACTER` data type by default, and the XML Schema `base64Binary` and `hexBinary` data types map to the Progress `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`.

> Note: If the temp-table or ProDataSet has a Progress definition, this option is ignored.

> ``field-type-mapping``

> An optional `CHARACTER` expression that evaluates to a comma-separated 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 Progress data type for a specific field from the XML Schema. Generally, this option is only used to map fields from non-Progress generated schema. When reading and writing Progress-generated XML Schema, there is little need to override field mappings because of the Progress extensions to standard XML Schema.

> ``field-name``

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

> The target 4GL data type for the specified field. The data type must be a valid Progress data type, and it must be compatible with the XML Schema type based on the Progress XML data type mapping rules. For example, any XML Schema type can be mapped to a Progress `CHAR` or `CLOB`, but an XML Schema `dateTime` can be mapped only to a Progress `DATE`, `DATETIME` or `DATETIME-TZ`.

> If you specify the Unknown value (`?`), the method uses the default data type.

> Note: If the temp-table or ProDataSet has a Progress definition, this option is ignored.

> For more information about the Progress XML data type mapping rules, see Appendix D, "XML Reference of Data Type and Code Page mappings".

> ``verify-schema-mode``

> An optional `CHARACTER` expression that specifies the mode in which the `READ-XMLSCHEMA( )` method verifies any XML Schema against an existing Progress definition. The expression must evaluate to `“LOOSE”` or `“STRICT”`. The default value is `“LOOSE”`.

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

> Table 22–3 lists the `READ-XMLSCHEMA( )` method schema verification modes.

> Table 22–3: READ-XMLSCHEMA( ) method verification mode
> When the mode is... | The READ-XMLSCHEMA( ) method...
> --- | ---
> `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. 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.
> `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 not present in both the XML Schema and the temp-table are ignored. 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 each match between a data relationship in the XML Schema that a data-relation in the ProDataSet, the field mapping must match for the parent and child buffers. 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.

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

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