Reads an XML document into a ProDataSet, temp-table, or temp-table buffer object. You can read data, schema, or both.
Return type: LOGICAL
Applies to: Buffer object handle, ProDataSet object handle, Temp-table object handle
READ-XML ( source-type , { file | memptr | handle | longchar } , read-mode , schema-location , override-default-mapping [ , field-type-mapping [ , verify-schema-mode ] ] ) |
For a WEB-CONTEXT system handle, the READ-XML( ) method reads an XML 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.
The following table lists the READ-XML( ) method modes for reading data.
When the mode is . . . | The READ-XML( ) method . . . |
---|---|
APPEND | Reads data from the XML document into the ProDataSet or temp-table object by adding new records to the existing records, without performing any record comparisons. If a record from the XML document exists in the object (that is, it results in a duplicate unique key conflict), the method generates an error message and returns FALSE. |
EMPTY | Empties the contents of the ProDataSet or temp-table object before reading in data from the XML document. |
MERGE | Reads data from the XML document into the ProDataSet or temp-table object by merging new records with existing records in the table. If a record from the XML document exists in the object (that is, it results in a duplicate unique key conflict), the method does not replace the existing record. If the record from the XML document does not exist in the object, the method creates a new record. |
REPLACE | Reads data from the XML document into the ProDataSet or temp-table object by merging new records with existing records in the table. If the record from the XML document exists in the object (that is, it results in a duplicate unique key conflict), the method replaces the existing record with the new record. If the record from the XML document does not exist in the object, the method creates a new record. |
If you specify the empty string ("") or the Unknown value (?), the AVM creates or verifies the object's schema using any XML Schema defined or referenced in the XML document.
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-XML( ) 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.
This option allows you to specify the ABL data type for a specific field from the XML Schema.
If you specify the Unknown value (?), the method uses the default data type mapping. For more information about the ABL XML data type mapping rules, see OpenEdge Development: Working with XML.
The following table lists the READ-XML( ) method schema verification modes.
When the mode is . . . | The READ-XML( ) method . . . |
---|---|
IGNORE | Ignores any XML Schema specified in schema-location, or defined in the XML Document. |
LOOSE for temp-table objects |
|
LOOSE for ProDataSet objects |
|
STRICT for temp-table objects |
|
STRICT for ProDataSet objects |
|
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 either the XML Schema file specified in schema-location, or the XML Schema defined or referenced in the XML document. If a dynamic temp-table is not in the PREPARED or CLEAR state, the method generates an error and returns FALSE.
ABL has a pair of attributes with overlapping purposes in how the AVM reads XML data, SERIALIZE-NAME and XML-NODE-NAME. Refer to the attribute entries for a full description of their interaction.
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 any XML Schema specified by schema-location, or defined or referenced in the XML document, against the object's schema, unless the verify-schema-mode is "IGNORE".
If the AVM cannot identify any XML Schema for the ProDataSet or temp-table object, (that is, schema-location is the empty string ("") or the Unknown value (?) and the XML document does not define or reference a schema, the AVM infers the schema from the data in the XML document.
For more information about creating schema from XML Schema, verifying XML Schema, or inferring schema from XML document text, see OpenEdge® Development: Working with XML.
The XML document can also contain before-image table data associated with a ProDataSet object. If the XML document data is in the Microsoft DiffGram format, the method reads the before-image data as well. In this case, if the ProDataSet or temp-table object is static and it does not have a before-image table defined, the method generates an error and returns FALSE. If the ProDataSet or temp-table object is dynamic, the method creates the before-image table automatically.
You cannot read an XML document into a database buffer.
The following code example creates a dynamic ProDataSet object from an empty ProDataSet handle, creates the object's schema from the specified XML Schema file, and populates the temp-tables with records from the specified XML document:
DEFINE VARIABLE cSourceType AS CHARACTER NO-UNDO. DEFINE VARIABLE cReadMode AS CHARACTER NO-UNDO. DEFINE VARIABLE lOverrideDefaultMapping AS LOGICAL NO-UNDO. DEFINE VARIABLE cFile AS CHARACTER NO-UNDO. DEFINE VARIABLE cSchemaLocation AS CHARACTER NO-UNDO. DEFINE VARIABLE cFieldTypeMapping AS CHARACTER NO-UNDO. DEFINE VARIABLE cVerifySchemaMode AS CHARACTER NO-UNDO. DEFINE VARIABLE lRetOK AS LOGICAL NO-UNDO. DEFINE VARIABLE hDSet AS HANDLE NO-UNDO. CREATE DATASET hDSet. ASSIGN cSourceType = "file" cFile = "dset.xml" cReadMode = "empty" cSchemaLocation = "cust-ord-inv.xsd" lOverrideDefaultMapping = ? cFieldTypeMapping = ? cVerifySchemaMode = ?. lRetOK = hDSet:READ-XML(cSourceType, cFile, cReadMode, cSchemaLocation, lOverrideDefaultMapping, cFieldTypeMapping, cVerifySchemaMode). |
The following code example creates a dynamic temp-table object from an empty temp-table handle, creates the object's schema from the specified XML Schema file, and populates the temp-table with records from the specified XML document:
DEFINE VARIABLE cSourceType AS CHARACTER NO-UNDO. DEFINE VARIABLE cReadMode AS CHARACTER NO-UNDO. DEFINE VARIABLE lOverrideDefaultMapping AS LOGICAL NO-UNDO. DEFINE VARIABLE cFile AS CHARACTER NO-UNDO. DEFINE VARIABLE cSchemaLocation AS CHARACTER NO-UNDO. DEFINE VARIABLE cFieldTypeMapping AS CHARACTER NO-UNDO. DEFINE VARIABLE cVerifySchemaMode AS CHARACTER NO-UNDO. DEFINE VARIABLE lRetOK AS LOGICAL NO-UNDO. DEFINE VARIABLE httCust AS HANDLE NO-UNDO. CREATE TEMP-TABLE httCust. ASSIGN cSourceType = "file" cFile = "ttcust.xml" cReadMode = "empty" cSchemaLocation = "ttcust.xsd" lOverrideDefaultMapping = ? cFieldTypeMapping = ? cVerifySchemaMode = ?. lRetOK = httCust:READ-XML(cSourceType, cFile, cReadMode, cSchemaLocation, lOverrideDefaultMapping, cFieldTypeMapping, cVerifySchemaMode). |