Websydian v6.1 online documentationOnline documentation - Websydian v6.5

Websydian DOM - Parts (DomServices 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:

If you are switching between documents it is therefore important that object references from one XML document (or object store) is not used in another XML document (or object storage).

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.

A deleted object reference should never be used in any subsequent calls.

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:

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.

Output parameters ExceptionCode Exception code saved on the error stack.
ErrorDescription Error description saved on the error stack.
ExceptionCode2 Exception code returned from ErrorPop indicating if the erorr stack is empty.

DomServices.ErrorPush

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

Input parameters ExceptionCode Exception code to push on the error stack.
ErrorDescription Error description to push on the error stack.
Output parameters ExceptionCode Exception code returned from ErrorPush indicating if the erorr stack is full or another error occurred.

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.

Input parameters ObjectStoreReference Reference to the ObjectStore where the document is located.
ObjectReference Reference to the XML document in the ObjectStore to be used. Returned by CreateDocument.
FileName String holding the filename.
Output parameters ExceptionCode Exception code returned in case of error.
LoadStatus Output indicating error returned by the XML parser in case of load error.

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.

Input parameters ObjectStoreReference Reference to the ObjectStore where the document is located.
ObjectReference Reference to the XML document in the ObjectStore to be used. Returned by CreateDocument.
FileName String holding the filename.
Output parameters ExceptionCode Exception code returned in case of error.
LoadStatus Output indicating error returned by the XML parser in case of load error.

DomServices.LoadDocumentFromFile

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

Input parameters ObjectStoreReference Reference to the ObjectStore where the document is located.
ObjectReference Reference to the XML document in the ObjectStore to be used. Returned by CreateDocument.
FileName String holding the filename.
Output parameters ExceptionCode Exception code returned in case of error.
LoadStatus Output indicating error returned by the XML parser in case of load error.

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.

Input parameters ObjectStoreReference Reference to the ObjectStore where the document is located.
ObjectReference Reference to the XML document to be saved.
FileName String holding the filename.
Encoding String holding the encoding to be used.
Version String holding information about XML version to be used.
Output parameters ExceptionCode Exception code returned in case of error.

DomServices.CreateDocument

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

Output parameters ExceptionCode Exception code returned in case of error.
ObjectDocument Reference to the XML document instance and root of the XML document.
ObjectStoreReference Reference to the ObjectStore where the document is located.

The DomServices.CreateDocument returns an ObjectDocument referring to the XML document created. This reference is overloaded and points both to the XML document in question but also to the top of the XML document. The top is the top of the XML document and not the root element of the 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.

Input parameters ObjectDocument Reference to the ObjectDocument returned by CreateDocument
ObjectStoreReference Reference to the ObjectStoreReference returned by CreateDocument
Output parameters ExceptionCode ExceptionCode returned in case of error.