XDATA

9.8A

The XDATA instruction allows generation and parsing of XML and JSON data structures. To define an XDATA, use the following statement format:

[label]

XDATA

Where:

label

Optional. A Data Label.

Flags Affected: NONE

Note the following:

XDATA creates HTML pages, SOAP messages, REST, and JSON data.
The XDATA object exists in all PLB runtimes and only supports methods to process the XML and JSON data.
The XDATA object is similar to the CLIENT and RUNTIME objects where these objects are not created.
There are no properties or events for a XDATA object.
There are no GUI PL/B instructions other than GUI methods that are used with a XDATA object.
The XData object methods return specific values.

Any PLB developer that uses the XDATA methods should have a working knowledge of the DOM, XML, and JSON concepts to be able to create\use well-formed XML\JSON documents.

Overview and Definitions:

DOM

The Document Object Model (DOM) is an interface for valid HTML and well-formed XML documents. The DOM relationships are described as follows:

The entire document is a document node.

Every XML element is an element node.

The text in the XML elements are text nodes.

Every attribute is an attribute node.

Comments are comment nodes

Terms

A DOM_ATTRIBUTE_NODE is formed as:

label: The 'label' is a named reference for the node. In XML the 'label' is the tag name (ie., label="value" ). In JSON, the 'label' is the name component in a JSON name/value pair (i.e. "label":value).
text: The 'text' is the value component for the node. In XML, the 'text' is the value (i.e., label="value"). In JSON, the 'text' is the value in a JSON name/value pair (i.e. "label":value).
JsonType: The 'jsontype' is optional which applies to the value component in a JSON name/value pair. The 'jsontype' defines the syntax format used for the value component. The value for JSON value may be enclosed in double quotes depending on the 'jsontype'.

A DOM_TEXT_NODE is formed as:

label: The 'label' does not exist for a DOM_TEXT_NODE.
text: The 'text' is the value component for the node. In XML, the 'text' is the value (i.e., label="value"). In JSON, the 'text' is the value in a JSON name/value pair (i.e. "label":value).
JsonType: The 'jsontype' is optional which applies to the value component in a JSON name/value pair. The 'jsontype' defines the syntax format used for the value component. The value for JSON value may be enclosed in double quotes depending on the 'jsontype'.

A DOM_ELEMENT_NODE is formed as:

label: The 'label' is a named reference for the node. In XML the 'label' is the tag name (ie. <label>value</label> ). In JSON, the 'label' is the name component in a JSON name/value pair (i.e. "label":value).
text: The 'text' does not exist for DOM_ELEMENT_NODE.
children nodes: The children nodes can be DOM_ATTRIBUTE_NODE, DOM_TEXT_NODE, or DOM_ELEMENT_NODE nodes that are used for the value component for the DOM_ELEMENT_NODE.
JsonType: The 'jsontype' is optional which applies to the value component in a JSON name/value pair. The 'jsontype' defines the syntax format used for the value component. The supported 'jsontype' values are only JSON_TYPE_ARRAY, JSON_TYPE_OBJECT, or JSON_TYPE_NONE.

Node

A Node represents a logical construct in a DOM type of of document. A node can be an element node, an attribute node, a text node, or other type.

The NODE types used in the XDATA implementation are defined as follows:

Root: Represents the entire document. This node is never created, but it is used for positioning.
DocumentType: Provides an interface to the entities or legal building blocks of an XML document.
ProcessingInstruction: Represents a node type that can occur anywhere in a document and is intended to carry instructions to an application.
Element: Represents an element that includes everything from (including) the element's start tag to (including) the element's end tag.
Attribute: Represents the attribute information used to describe the XML element.
Text: Represents textual content in an element.
Comment: Comment represented in a XML document as content between ''. In XML, the character sequence '--' cannot be used within a document.

Positioning

The nodes in the node tree have a hierarchical relationship with each other. The terms parent, child, and sibling are used to describe the node relationships. The supportrf node positions are defined as follows:

Node Tree: The XML DOM views an XML document as a tree-structure. The tree structure is called a node-tree. All nodes can be accessed through the tree. Their contents can be modified or deleted, and new elements can be created. A node tree starts at the root node and branches out to the text nodes at the lowest level of the tree.
Node Parents, Children, and Siblings: The nodes in a node tree have a hierarchical relationship with each other. The terms parent, child, and sibling are used to describe the relationships. Parent nodes have children. Children on the same level are called siblings. The following characteristics are used for nodes:

In a node tree, the top node is called the root.

Every node, except the root, has exactly one parent node.

A node can have any number of children.

A leaf is a node with no children.

Siblings are nodes with the same parent.

Positioning Parameter Values

A position parameter value can be a position type or a position type added to a value returned by the GetPosition method. The basic positioning values are defined as follows:

Parameter	Value	Meaning
MOVE_CURRENT_NODE	0	Stay at the current node location.
MOVE_PARENT_NODE	1	Move to parent node.
MOVE_FIRST_CHILD	2	Move to the first child node
MOVE_LAST_CHILD	3	Move to last child node.
MOVE_PREVIOUS_SIBLING	4	Move to previous sibling node.
MOVE_NEXT_SIBLING	5	Move to next sibling node.
MOVE_ROOT_NODE	6	Move to root position.

JSON Specifics

See the following link for basic JSON syntax elements and rules:

http://www.w3schools.com/js/js_json.asp

JSON only uses the DOM_ATTRIBUTE_NODE, DOM_ELEMENT_NODE, and DOM_TEXT_NODE nodes.

The XDATA process is as follows:

DOM_ATTRIBUTE_NODE translates as:

LABEL becomes the name in the name/value pair.

TEXT becomes the value in the name/value pair.

DOM_ELEMENT_NODE translates as:

LABEL becomes the name in the name/value pair.

Children nodes become the value in the name/value pair.

DOM_TEXT_NODE translates as:

TEXT becomes the value in the name/value pair.

A JSON array is a DOM_ELEMENT_NODE with a label of array and jsontype of JSON_TYPE_ARRAY. It can have multiple DOM_TEXT_NODE as values and multiple DOM_ELEMENT_NODE as object values.

A JSON object is a DOM_ELEMENT_NODE with a label of object and jsontype of JSON_TYPE_OBJECT. It can have multiple DOM_ATTRIBUTE_NODE and DOM_ELEMENT_NODE nodes as key value pairs.

XDATA to JSON Syntax Format:

The JSON format is syntactically identical to the code for creating JavaScript objects. Because of this similarity, a JavaScript program can easily convert JSON data into native JavaScript objects.

JSON Syntax Rules

Data is in name/value pairs.

Data is separated by commas.

Curly braces hold objects.

Square brackets hold arrays.

JSON Data - A Name and a Value.

JSON data is written as name/value pairs, just like JavaScript object properties.

A name/value pair consists of a field name (in double quotes), followed by a colon, followed by a value:

"firstName":"John"

Where:

"firstName" is a JSON name field.

':' colon character separates the name and value fields.

"John" is the JSON value field.

Note: JSON names require double quotes whileJavaScript names do not.

XML Node Creation Types

DOM_ATTRIBUTE_NODE: Generated as label="value" inside an element tag.

DOM_COMMENT_NODE: Generated as

DOM_DOCUMENT_TYPE_NODE: Generated as <!DOCTYPE name PUBLIC "pubid" "sysid">

Example:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict //EN" "-//W3C//DTD XHTML 1.0 Strict//EN" " http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

DOM_ELEMENT_NODE: Generated as a <label></label> set.

DOM_PROCESSING_INSTRUCTION_NODE: Generated as <?target data?>.

DOM_TEXT_NODE: Generated as just text.

See Also: Object Definitions