XMLParseString

Description

Parses an XML string and determines whether the string is well formed or complies with a specified grammar.

Syntax

XMLParseString ( xmlstring {, validationscheme }{, parsingerrors } {, namespaceprocessing {, schemaprocessing {, schemafullchecking }}})

Argument

Description

xmlstring

A string that holds the XML document to be parsed.

validationscheme (optional)

A value of the ValSchemeType enumerated datatype specifying the validation method used by the SAX parser. Values are:

  • ValNever! -- Do not report validation errors.

  • ValAlways! -- Always report validation errors. Use ValAlways! only when you know there is a DTD or schema against which the file can be validated.

  • ValAuto! -- (default) Report validation errors only if a grammar is specified.

parsingerrors (optional) 

A string buffer to which error messages can be saved. If not specified or set to null, errors are shown to the user in a dialog box.

namespaceprocessing (optional)

A boolean specifying whether name space rules are enforced. When set to true, the parser enforces the constraints and rules defined by the W3C recommendation on namespaces in XML.

If validationscheme is set to ValAlways! or ValAuto!, the document must contain a grammar that supports the use of namespaces.

The default is false.

schemaprocessing (optional)

A boolean specifying whether schema support is enabled. When set to false, the parser does not process any schema found.

If schemaprocessing is true, namespaceprocessing must also be set to true.

The default is false.

schemafullchecking (optional) 

A boolean specifying whether schema constraints are checked. When set to true, the schema grammar is checked for errors.

Setting schemafullchecking to true has no effect unless schemaprocessing is also set to true.

The default is false.


Return value

Long.

Returns 0 for success and one of the following negative values if an error occurs:

-1 -- Parsing error

-2 -- Argument error

Usage

Use XMLParseString to validate an XML string against a DTD or XML schema before proceeding with additional processing.

If no DTD or schema is included or referenced in the string, XMLParseString checks whether the string contains well-formed XML. If the XML string fails validation or is not well-formed, XMLParseString returns -1.

XSD (schema) files are in XML format and you can check them for well-formedness. The validation scheme must be ValAuto!, which is the default validation scheme, because ValAlways! requires that there be a schema or DTD against which to validate the file.

For example, given the following schema file, the parser fails because there is no external XSD file that defines xs:schema, xs:element, and xs:complextype. The schema is defined by the namespace http://www.w3.org/2001/XMLSchema.

<?xml version="1.0" encoding="UTF-8"?>
  <xs:schema xmlns:xs=
                 "http://www.w3.org/2001/XMLSchema">
     <xs:element name="test3">
       <xs:complexType>
          <xs:sequence>
             <xs:element ref="test3_row" maxOccurs=
                           "unbounded" minOccurs="0"/>
          </xs:sequence>
       </xs:complexType>
     </xs:element>
  </xs:schema>

Using ValAlways! also fails for an XML file if there is no schema defined or the reference does not point to a valid schema. If you use ValAuto!, validation is performed only if the schema or DTD file is present in the desired location. If it is not present, only well-formedness is checked.

To suppress the display of message boxes if errors occur, specify a string value for the parsingerrors argument.

The files pbxercesNN.dll and xerces-c_XX.dll, where NN represents the PowerBuilder version and XX represents the Xerces version, must be deployed with the other PowerBuilder runtime files in the search path of any application or component that uses this function.

Examples

These statements parse an XML string. If a DTD is included or referenced, the string is validated. Otherwise the parser checks for well-formedness:

// string argument as_xmlstring passed in
long ll_ret

ll_ret = XMLParseString(as_xmlstring)

These statements parse an XML string, validate against a given XML schema, and save any errors that occur in a string variable. If errors occur, no message boxes display. If no schema is included or referenced in the string, XMLParseString returns -1:

long ll_ret
string ls_xmlstr, ls_err

ll_ret = XMLParseString(ls_xmlstr, ValAlways!, ls_err, TRUE, TRUE)

These statements parse an XML string, validate against a given DTD, and save any errors that occur in a string variable. If errors occur, no message boxes display. If no DTD is included or referenced in the string, XMLParseString returns -1. If the string passes validation, it is imported into a DataWindow control:

long ll_ret
string ls_xmlstr, ls_err

ll_ret = XMLParseString(ls_xmlstr, ValAlways!, ls_err)
if ll_ret = 1 then dw_1.ImportString(ls_xmlstr)

See also

ImportString

XMLParseFile

ImportString method for DataWindows in the section called “ImportString” in DataWindow Reference.