XMLParseFile

Description

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

Syntax

XMLParseFile ( xmlfilename {, validationscheme }{, parsingerrors } {, namespaceprocessing {, schemaprocessing {, schemafullchecking }}})

Argument

Description

xmlstring

A string whose value is the name of the XML file 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.

  • 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 display in a message 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 XMLParseFile to validate an XML file against a DTD or XML schema before proceeding with additional processing.

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

Because XSD You can also check the well-formedness of an XSD file because they are in XML format. The validation scheme must be ValAuto!, which is the default validation scheme.

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 document. If a DTD is included or referenced, the document is validated. Otherwise the parser checks for well-formedness. If the document passes validation, it is imported into a DataWindow control:

long ll_ret

ll_ret = XMLParseFile("c:\temp\mydoc.xml")
if ll_ret = 0 then dw_1.ImportFile("c:\temp\mydoc.xml")

These statements parse an XML document and save any errors in the string variable ls_err. If errors occur, no message boxes display. If a DTD is included or referenced, the document is validated. Otherwise the parser checks for well-formedness:

long ll_ret
string ls_err
ll_ret = XMLParseFile("c:\temp\mydoc.xml", ls_err)

These statements parse an XML document. If an XMLSchema is included or referenced, the document is validated, otherwise the parser checks for well-formedness:

long ll_ret
ll_ret = XMLParseFile("c:\temp\mydoc.xml", TRUE, TRUE)

These statements parse an XML document, 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 file, XMLParseFile returns -1:

long ll_ret
string ls_err
ll_ret = XMLParseFile("c:\temp\mydoc.xml", ValAlways!, ls_err, TRUE, TRUE)

These statements parse an XML document, validate against a given XML schema, and parse the schema itself for additional errors. If no schema is included or referenced in the file, XMLParseFile returns -1:

long ll_ret
string ls_err
ll_ret = XMLParseFile("c:\temp\mydoc.xml", ValAlways!, ls_err, TRUE, TRUE, TRUE)

These statements parse an XML document, 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 file, XMLParseFile returns -1:

long ll_ret
string ls_err
ll_ret = XMLParseFile("c:\temp\mydoc.xml", ValAlways!, ls_err)

These statements parse an XSD file and test it for well-formedness. You must use ValAuto! when you parse an XSD file because there is no external schema associated with it. However, you do not need to specify the option when you call the function because it is the default validation method:

long ll_ret
ll_ret = XMLParseFile ("c:\mydoc.xsd")

See also

ImportFile

XMLParseString

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