XML Mapper

ToolsXML Mapper

At design-time, defines the mappings between generic XML documents and the data packets that client datasets use. Each mapping describes the correspondences between the nodes of an XML document and the fields in a data packet.

You can define mappings from an existing XML schema (or document) to a client dataset that you define, from an existing data packet to a new XML schema you define, or between an existing XML schema and an existing data packet.

Document View Page

This page shows the contents of the currently loaded XML document, represented as a hierarchical tree view. Each node in the tree represents a tag or tag attribute in the XML document. Next to each node is an icon that indicates the type of tag it represents:

Item	Description
	Represents an element node that is a tag that acts as a parent to other nodes (tags), but does not have a value. The name of the node is the tag name. Typically, element nodes map to datasets (the data packet itself or a nested detail set), although they can also map to fields whose values are a composite of the child node values.
	Represents a text node. Text nodes represent tagged elements with text values. In the tree, they have the form Nodename="TextValue", where Nodename is the tag name and TextValue is the text that appears between the starting tag and the ending tag. Typically, text nodes map to fields in the corresponding data packet.
	Represents an attribute node. Attribute nodes correspond to attributes of the parent element’s tag in the XML document. In the tree, attributes have the form Nodename="AttributeValue", where Nodename is the name of the attribute and AttributeValue is its value. Typically, A nodes map to fields in the corresponding data packet, where the element for which they are attributes maps to a record.
	Represents a nested node. Nested nodes are element nodes that can appear replicated sequentially in the XML document. Typically, nested nodes map to records in the corresponding data packet.
Data View	If unchecked, the hierarchy displays only the names and types of nodes. No values are shown for text or attribute nodes, and only a single instance is shown for any nested nodes. If checked, the hierarchy displays sample values on text and attribute nodes, and repetitions of nested nodes. If you loaded a sample XML file, the Data View shows the values stored in that file. If the document was generated from a schema or data packet, sample values are generated for the nodes. When examining a large XML document, it is sometimes easier to uncheck Data View, so you can see more of the logical structure with the detailed information removed.

Schema View Page

This page shows the XML schema information. This page has three tabs, which represent the different schema formats supported by XML mapper. These include DTD, XDR (reduced XMLData), and XSD (XML schema). The information on the Schema View page can be read from a file or deduced from an actual XML document.

Node Properties Page

This page lets you assign properties to the currently selected node in the XML document pane. These properties are used when generating a transformation file to ensure that data packets generated from XML documents have the correct field types and constraints, and that XML documents generated from data packets have the correct nodes. When you generate a transformation file, it reflects the values currently specified on the Node Properties page.

Item	Description
UTF-8 encoded	Controls whether extended characters are encoded using UTF-8 (when checked) or using an escape sequence in the XML (when unchecked). When checked, the Data Format property for Strings, Memos, and WideStrings changes from ANSI to UTF-8.
User Defined Translation	Controls whether the selected node should be transformed automatically. This allows you to perform conversions that are not simple one-to-one mappings that can be specified by giving a data type. For example, you can create a user-defined node to convert an element node that has children for first name and last name into a single "full name" field in the data packet. When you check the User Defined check box, you must assign an ID string to represent the node. This ID string is passed to the OnTranslate event handler of TXMLTransform so that you can perform the translation in code. If you do not identify a node as user-defined, the OnTranslate event does not occur for the node.
Node Description	Optional. Enter a description of the node. This description is not added to the XML document or the data packet, but is useful for identifying the purpose of a base set element when you are saving property sets to a node repository file

Tip: To save the current node settings to a node repository file, right-click and choose Save Repository. To read a set of node settings from a node repository file, right-click and choose Open Repository. To back out all changes made on the Node Properties

page, reverting to the values deduced from the XML document, right-click and choose Clear.

Mapping Page

This page lets you specify the mapping between fields in the data packet and nodes in the XML document, create a transformation file, and save the transformation file.

The top of the page displays a two-column table that lists the nodes from the XML document and the corresponding fields in the data packet. When you first display the mapping page, this table is empty. In order to define a mapping, you must fill this table.

Note: You can only add nodes with values (text and attribute nodes), or nodes that have been marked as user-defined using the Node Properties

page.

Field View Page

This page displays the field attributes for all the fields in the data packet. Each node in the hierarchy represents a dataset, field, or field attribute:

Item	Description
	Represents the entire data packet or a dataset field. The children of a dataset node represent the fields in that dataset.
	Represents a field that is not a dataset field. The children of a field node represent the attributes of the field.
	Represents a field attribute, such as the data type, maximum length, and so on. The node is labeled with a string of the form AttributeName = Value, where AttributeName is the name of the field attribute and Value is its value.

Datapacket View Page

This page displays the structure of the data packet. The icons in this view are the same as those in the XML document pane, because data packets can be treated as special types of XML documents.

Item	Description
	Represents an element node. Element nodes in data packets represent datasets or dataset fields.
	Represents an attribute node. Attribute nodes in data packets represent fields (unless they are dataset fields).
	Represents a nested node. Nested nodes in data packets represent records.

Note: XML mapper can use a data packet in binary format (a .cds

file) as well as data packets that have been saved as XML. If you use a data packet in binary format, XML mapper converts it to XML format.