xmlToStruct

Convert an XML document to a Struct.

Example: xmlToStruct/full vStruct, INPUT_FLD

Conversion with /full

By default XML comments, DOCTYPE declaration, and namespace declarations are ignored when converting to Structs.

To include them, use the /full switch. This ensures that all XML constructs, including comments, doctype declaration, and namespace declarations (if present), are also converted to Structs. This is critical if you need to reconstruct an equivalent XML document from the Struct.

Note:  The use of /full does not imply /schema or /whitespace.

If /full is specified, and <![CDATA[...]]> occurs within the character data, it is converted to a separate nameless scalar Struct with the xmlClass tags set to CDATA. Otherwise, the <![CDATA[...]]> piece is incorporated into one scalar Struct for the whole character value; it becomes indistinguishable from the rest of the data.

Namespace Handling

Qualified names are those consisting of namespace URI that qualify a local name. For example, the local name schema can be qualified by the namespace "http://www.w3.org/2001/XMLSchema" which together provide a unique identifier.

Namespaces can be defined with an alias. For example, xmlns:s="http://www.w3.org/2001/XMLSchema" means that within the scope of this definition s is the namespace http://www.w3.org/2001/XMLSchema".

An alias can be used in a qualified name. For example, s:schema and its semantics are completely defined by the XML Schema Definition and should not be confused with any other meaning schema.

By default, xmlToStruct recognizes qualified names only in element and attribute names, and records the namespace declaration in the $tags members of the element or attribute Struct node.

When xmlToStruct/full is used, it also recognizes:

• Namespace declarations that are not actually used in a qualified name
• Qualified names that are used as values of elements and attributes. This type of construction is used in specialised XML documents that describe or manipulate other XML documents.

Conversion with /schema

If /schema is used, the specified schema (or schemas) determine which whitespace is significant and which is not.

If schemas are specified, each Namespace+Location pair in the SchemaList is added to the list of schema locations as if they were specified in the XML source itself using the schemaLocation= keyword.

There can be only one location without accompanying namespace in the list, because the XML parser supports only one location specified by the noNamespaceSchemaLocation keyword.

For example:

• Index list has one item, a schema location:

  xmlToStruct vStruct, "file.xml", "schema.xsd"

• Index list has one item, an associated list with only a schema location; this is equivalent to the previous command:

  xmlToStruct vStruct, "file.xml", "LOCATION=schema.xsd"

When multiple schemas are specified, Namespace + Location pairs must be passed as an associated list. For example:

vSchemaList = "" ; initialize outer list
vItems = ""      ; initialize sublist 

; create Namespace+Location sublist
putitem/id vItems, "NAMESPACE", "http://www.shiporder.com"
putitem/id vItems, "LOCATION", "shiporder.xsd"
putitem vSchemaList, -1, vItems ; add items list to outer list

; add a second pair:
vItems = ""
putitem/id vItems, "NAMESPACE", "http://www.customs.com"
putitem/id vItems, "LOCATION", "custom.xsd"
putitem vSchemaList, -1, vItems

xmlToStruct vStruct, "file.xml", vSchemaList

Data Types

If /schema is not specified, the Uniface data type of every element and attribute is string.

If the /schema switch is specified, elements and attributes with predefined data types are included in the Struct as scalar Structs of matching Uniface data types. The values themselves are converted to Uniface format.

Note:  Supplying a schema list in the third parameter does not imply that schema information is to be included; the parameter may be supplied just to satisfy /validate, not because you want the schema information.

$procReturnContext for xmlToStruct

$procReturnContext contains context and error information about the conversion in the form of a nested Uniface list.

Context=xmlToStruct ;}
{Infos=Number ;
{Warnings=Number ;} 
{Errors=Number ;}
{DETAILS=ID=MsgNum !!;SEVERITY=Type !!;MNEM=Mnemonic !!;DESCRIPTION=ErrorDescription !!;CURRENTSTRUCT=Struct !!;ADDITIONAL=TAGNAME=Name !!!;TAGVALUE=Value !!!;EXPECTED=ExpectedValue}  { !;ID= ...}