DOM Parser User's Guide

SOLA DOM API Overview

SOLA

Ve Revision Date: August 2017

rsion 6.4

SOLA DOM API Overview

Table of Contents

Table of Contents................................................................................. ii

The SOLA DOM API .............................................................................. 3

SOLA DOM API Functions ................................................................ 5

Data Conversion Utility XMLPC107 .................................................. 11

SOLA DOM API Overview

The SOLA DOM API

The Document Object Model (DOM) is a specification designed by the World-

Wide-Web Consortium (W3C) to provide an object oriented and vendor

independent way to inquire on and modify XML documents. DOM works by

loading the entire XML document into memory and then converting the

document into a tree structure. Inquiring on, modifying and creating a new

XML document is done using methods provided by the DOM specification.

SOLA provides the SOLA DOM API to inquire on, modify and create XML

documents. The SOLA DOM API is a “DOM like” API that implements the

functionality of DOM in a format that is easily used by procedural languages

like COBOL. The SOLA DOM API can be used by CICS transactions and batch

jobs. It provides functions to inquire on an XML document repeatedly in any

direction and modify an existing document. The API also provides methods to

create new XML documents. This document lists all the features of the SOLA

DOM API and provides many samples for use in mainframe programs running

in CICS and batch.

In most cases, the SOLA DOM API is identical for CICS and batch programs.

In those instances where the APIs differ, the differences will be noted in the

text.

Advantages

The SOLA DOM API provides an easy and efficient way for any mainframe

program to process XML documents. Performance (CPU utilization and

memory consumption) was a major focus in the design and development of

the SOLA DOM API. To keep CPU consumption to a minimum, the SOLA DOM

API is highly optimized and is written entirely in Assembler for z/OS. The

SOLA DOM API has a relatively small memory footprint for the DOM tree due

to the fact that it parses the XML document and normalizes it in place without

requiring any additional memory to hold the node values. The DOM tree

contains pointers to the parsed and normalized document, thereby holding the

memory footprint to a minimum.

The SOLA DOM API makes it easy for the mainframe programmer to produce

well-formed XML without the need to perform complex string manipulations.

Without the SOLA DOM API, the programmer would have to follow the XML

SOLA DOM API Overview

specifications provided by the W3C which can be a time consuming and

daunting task.

For example, the following table shows incorrect XML formations that will be

rejected by an XML parser:

<SSN#>212-99-9654</SSN#>

The element name can’t contain

“#” Character in XML version 1.0

<SecurityName>AT&T

</SecurityName>

The special entity “&” should be

represented as &

Because the SOLA DOM API conforms to the W3C specifications, XML

documents created using the SOLA DOM API will always be valid and well

formed.

SOLA DOM API Overview

SOLA DOM API FUNCTIONS

The SOLA DOM API is an assembler program callable from any mainframe

program. The API supports inquiry and modification of XML documents as well

as the creation of new XML documents.

XML Inquiry Functions

getAttribute

This function retrieves the value for a given

attribute name in a name/value pair.

This function can be used in CICS and batch.

getAttributeAddress

This function is identical to getAttribute, except

that the attribute address is returned in place of

the attribute value.

This function can be used in CICS and batch.

getAttributeAddressById

The getAttributeAddressById function is identical

to getAttributeById, except that the attribute

value address is returned in place of the attribute

value.

This function can be used in CICS and batch.

getAttributeArray

This function retrieves an array containing all the

attributes for a given element node.

This function can be used in CICS and batch.

getAttributeById

This function retrieves an attribute and its value

using a given node Id.

This function can be used in CICS and batch.

getElementAddress

This function is identical to

getElementByTagName, except that the element

value address is returned in place of the element

value.

This function can be used in CICS and batch.

SOLA DOM API Overview

getElementAddressById

The getElementAddressById function is identical

to getElementById, except that the element value

address is returned in place of the element value.

This function can be used in CICS and batch.

getElementById

This function retrieves an element and its child

text node using a given node Id.

This function can be used in CICS and batch.

getElementByTagName

The getElementByTagName retrieves an element

node by its tag name.

This function can be used in CICS and batch.

getElementByXPath

This function retrieves an element and its child

text node for a given XPath expression.

This function can be used in CICS and batch.

getNamespace

This function retrieves the value of a namespace

associated with a namespace unique node

identifier.

This function can be used in CICS and batch.

Parse

This function parses, normalizes and creates the

tree structure for a given input XML document.

This function can be used in CICS and batch.

resetSelectAttrNodes

This function is used to reset the internal counters

used by the selectAttrNodes function. The

function should only be used in conjunction with

the selectAttrNodes function when it is operating

in an iterative mode.

This function can be used in CICS and batch.

SOLA DOM API Overview

resetSelectNodes

This function is used to reset the internal counters

used by the selectNodes function. The function

should only be used in conjunction with the

selectNodes function when it is operating in an

iterative mode.

This function can be used in CICS and batch.

selectAttrNodes

This function is used to inquire on either the total

number of attribute nodes in an XML document, to

get a particular attribute in the sequence or

retrieve attributes iteratively.

This function can be used in CICS and batch.

selectAttrNodesAddress

This function is identical to selectAttrNodes,

except that the address of the attribute value is

returned instead of the value of the attribute.

This function can be used in CICS and batch.

selectNodes

This function is used to inquire on either the total

number of element nodes in an XML document, to

get a particular element in the sequence or

retrieve elements iteratively.

This function can be used in CICS and batch.

selectNodesAddress

This function is identical to selectNodes, except

that the address of the element is returned

instead of the value of the element.

This function can be used in CICS and batch.

SOLA DOM API Overview

XML CREATION AND MODIFICATION FUNCTIONS

appendChild

This function appends a new child element to a

specified parent element. Optionally, a text node

value can be attached to the element.

This function can be used in CICS and batch.

appendChildBefore

This function is used to add an element before a

particular element. The element node to be

added will share the same parent as the element

that it is to be appended before.

This function can be used in CICS and batch.

appendChildNL

This function is identical to appendChild, except

that it will also insert a newline character into the

document before appending the child element

node.

This is a batch only function.

appendTextNode

This function is used to add a child text node to

an element node.

This function can be used in CICS and batch.

createDocument

This function creates the root element of an XML

document.

This function can be used in CICS and batch.

SOLA DOM API Overview

finalize

The finalize function is used to finalize and

optionally retrieve a newly created XML document.

Finalize will convert the DOM tree into an XML

stream, as it does so all open tags will be closed

and the document will be made ready to be

externalized. The finalize function returns a

pointer to the XML document.

Once finalized, the document can be accessed

with the address pointer. Alternatively, the

document can be accessed using the retrieve

function.

This function can be used in CICS and batch.

getXMLLength

This function retrieves the length of the completed

XML document.

This is a batch only function.

removeNode

This function removes any type of node (element,

attribute or namespace node) from an XML

document. To remove text nodes, use the

updateTextNode function.

This function can be used in CICS and batch.

retrieve

This function finalizes the document and then gets

the complete (if appendChildNL was not used)

document and copies it to a data area that you

provide. The SOLA DOM API will then release any

storage space used by the DOM tree and internal

control block.

If appendChildNL was used then the retrieve

function will fetch the document in pieces, each

piece ending in a newline.

This function can be used in CICS and batch.

setAttribute

This function is used to add and attach attributes

(name/value pairs) to an element.

This function can be used in CICS and batch.

SOLA DOM API Overview

setNamespace

This function is used to add and attach a

namespace to an element.

This function can be used in CICS and batch.

updateAttribute

This function is used to update the text of an

existing attribute. Changing the attribute name is

not allowed (to change the name of an attribute

you must first remove and then set the attribute).

This function can be used in CICS and batch.

updateTextNode

This function is used to change the value of or to

remove an existing text Node under an element

node.

This function can be used in CICS and batch.

SOLA DOM API Overview

Miscellaneous Functions

freeStorage

This function frees any storage that has been

acquired by the DOM parser and SOLA DOM

API.

This function can be used in CICS and batch.

DATA CONVERSION UTILITY XMLPC107

SOLA provides a utility program, XMLPC107, to provide data conversion

between native mainframe formats and XML. The utility is an assembler

program that is implemented with a callable interface.

Although the utility provides functions for converting character strings, it

should not be used for these conversions if you are using the SOLA DOM API.

This is because the SOLA DOM API uses the utility internally for XML encoding

and the effect of encoding a string twice is unpredictable.