Websydian DOM - Parts (DomServices Function Suite)

Introduction    Installation    Other Uses    Parts

• DomAbstract Function Suite

• DomInterfaces Function Suite

• DomServices Function Suite

  • Understanding the Object Store

    • DomServices.DeleteObjectReference

  • Error Handling Functions

    • DomServices.ErrorClear

    • DomServices.ErrorPop

    • DomServices.ErrorPush

  • DomServices Functions

    • DomServices.InitializeDom

    • DomServices.TerminateDom

    • DomServices.LoadDocumentFromFile

    • DomServices.CreateDocument

    • DomServices.SaveDocumentToFile

    • DomServices.DestroyDocument

• XmlParsers Function Suite

• XPath Function Suite

The DomServices function suite contains functions which are not part of the DOM standard, but nevertheless are necessary when working with XML documents. The DomServices suite also scopes functions that allow the Websydian developer to access the error stack which is part of the Websydian DOM implementation.

Understanding the ObjectStore

As CA Plex does not support objects an object store has been implemented in Websydian TransacXML. The object store holds references to objects created by the native XML parser, so all that is returned to the CA Plex application is a numeric value representing a reference stored in the object store. The numeric value can be stored in an CA Plex field and be used as input and output to and from Websydian TransacXML functions.

For each XML document (created by CreateDocument) an object store is created. This object store holds references to objects belonging to the created XML document. This means that all DOM functions in TransacXML requires two object references:

• A reference to the object store holding objects for a particular XML document.
• A reference to a DOM object within the above object store.

DomServices.DeleteObjectReference

Deletes an object reference in the object store. The input parameter ObjectReference contains the reference to the object that should be deleted.

Please note that only the reference is deleted. The object itself is not removed. To remove objects use the appropriate DOM functions to accomplish this; e.g. Node.removeChild.

Error Handling Functions

WSYDOM implements an error stack making it easier to trace errors in the XML parser. Whenever an error occurs in the parser or any function of the Websydian TransacXML pattern, an element is pushed onto the error stack. Each error stack element contains two pieces of information:

• an exception code (ExceptionCode) 
• a description of the error (ErrorDescription)

ExceptionCode contains the exception code corresponding to the error which occurred in the parser. For a list of all the possible error codes please refer to this document.

ErrorDescription contains a textual description of the error. 

The error stack element can subsequently be popped from the error stack in an action diagram.

To read more about error handling in TransacXML please read this document.

The following error handling functions are available to the Websydian developer:

DomServices.ErrorClear

Removes all elements from the error stack.

DomServices.ErrorPop

Pops an element from the error stack making the information in the element available to the Websydian developer. For an example of implementing the ErrorPop function see the action diagram of the function ImportXMLDocument.

DomServices.ErrorPush

Pushes an error element on the error stack. The parameter list can be seen in the table below.

Typically this function is only used when developing abstract low-level patterns in TransacXML.

Other DomServices Functions

DomServices.InitializeDom

This function initializes the parser and the Websydian DOM layer by setting up the ObjectStore and the error stack. This function has to be called prior to performing any XML processing.

DomServices.TerminateDom

TerminateDom clears down the XML environment. This function should be called after processing all the XML document. A call to the TerminateDom function will release memory allocated by objects in the Websydian DOM and unloads the parser. TerminateDom should be called as many times as InitializeDom has been called. Failing to call the TerminateDom will result in memory leaks.

DomServices.LoadDocumentFromFile

Loads an XML file into memory. Requires that CreateDocument has been called.

In Windows this function will cause a parser error if the file specified in the FileName parameter could not be found or opened. The returned error description will then be:

Parse error (800C0006): 'The system cannot locate the object specified.' in line 0 at position 0. Source text: '(null)'.

DomServices.SaveDocumentToFile

Writes XML document found in memory to a file.

DomServices.CreateDocument

Creates an XML document in memory, and returns an reference to the new XML document.

DomServices.DestroyDocument

Removes an XML document from  memory. Empties the ObjectStore by removing all reference to objects belonging to a specific XML document. Failing to call this function will result in an memory leak.