fwXML  8.4.0
fwXML.ctl File Reference
private const int fwXml_PARSING_DOWNORACROSS = 0
 
private const int fwXml_PARSING_WHEN_LEAVING = 1
 
const int fwXml_SAXSTARTELEMENT = 2
 
const int fwXml_SAXENDELEMENT = 3
 
const int fwXml_SAXTEXT = 6
 
const int fwXml_CONTAINS_SIMPLE_ELEMENT_NODES = 0
 
const int fwXml_CONTAINS_TEXT_NODES = 8
 
const int fwXml_CONTAINS_COMMENT_NODES = 256
 
const int fwXml_CONTAINS_COMPLEX_ELEMENT_NODES = 2
 
const string fwXml_CHILDNODESTYPE = "fwXml_ChildNodesType"
 
const string fwXml_CHILDSUBTREEID = "fwXml_ChildSubTreeId"
 
private int _fwXml_getTypeOfCallback (int parsingDownAcrossOrUp, int nodeType)
 
private void _fwXml_parseSaxRecursive (int documentId, mapping callBackList, int level, int topNodeId, dyn_string &exceptionInfo)
 
public int fwXml_parseSaxFromFile (string xmlDocumentName, mapping callBackList, dyn_string &exceptionInfo)
 
private void _fwXml_getElementsRecursive (unsigned documentId, int topNodeId, string tagName, dyn_int &elements, dyn_string &exceptionInfo)
 
public dyn_int fwXml_elementsByTagName (unsigned documentId, int topNodeId, string tagName, dyn_string &exceptionInfo)
 
public bool fwXml_containsNodeTypes (int setOfTypes, int requestedTypes)
 
public int fwXml_childNodesContent (unsigned documentId, int topNodeId, dyn_string &node_names, dyn_anytype &attributes, dyn_string &nodevalues, dyn_string &exceptionInfo)
 
public int fwXml_appendChildContent (unsigned documentId, int topNodeId, dyn_string node_names, dyn_anytype attributes, dyn_string nodevalues, dyn_string &exceptionInfo)
 

Detailed Description

This library contains the XML SAX function call and some additional XML DOM function calls.

Creation Date
01/12/2008
Modification History
09/11/2015: Code Improvement as a result of Crucible 19/08/2013: Generalise fwXml_appendChildContent Bug in recovery mechanism of fwXml_appendChildContent 06/04/2010: Removed .dll extension from #uses 22/06/2009: Added fwXml_appendChildContent 01/12/2008: Initial version
Constraints
For PVSS 3.6 SP2 and later versions
Usage
Public
PVSS managers
UI, CTRL
Author
01/02/2016 - James Hamilton (EN-ICE) 01/12/2008 - Daniel Davids (IT-CO)

Function Documentation

private int _fwXml_getTypeOfCallback ( int  parsingDownAcrossOrUp,
int  nodeType 
)
'_fwXml_getTypeOfCallback' calculates the type of 'callback' that needs to be executed!
Constraints
None
Usage
Private
PVSS managers
UI, CTRL
Parameters
parsingDownAcrossOrUpinput, the parsing direction
nodeTypeinput, the node-type of the encopuntered node
Returns
output, the type of callback
Philosophy
The philosophy behind this is that a non-leaf node can be parsed in two directions, when going down (pre-fix scanning) or when going up (post-fix scanning). A leaf node can only be parsed in one direction, across (infix scanning).
To make an association between a note-type and the corresponding type of 'callback', one has made the following rule: the type of callback to be executed when parsing down or across is twice the node-type's value; the type of callback to be executed when parsing up is twice the node-type's value plus one!
private void _fwXml_parseSaxRecursive ( int  documentId,
mapping  callBackList,
int  level,
int  topNodeId,
dyn_string &  exceptionInfo 
)
'_fwXml_parseSaxRecursive' called by 'fwXml_parseSaxFromFile' and itself in a recursive way.
Constraints
None
Usage
Private
PVSS managers
UI, CTRL
Parameters
documentIdinput, the document-ident of the loaded Xml file
callBackListinput, the callback functions to be called while parsing
levelinput, the current nesting-level of the recursive calls
topNodeIdinput, the top node-ident from which the sub-tree is parsed
exceptionInfoinout, returns details of any exceptions
Returns
void
public int fwXml_parseSaxFromFile ( string  xmlDocumentName,
mapping  callBackList,
dyn_string &  exceptionInfo 
)
'fwXml_parseSaxFromFile' parses an Xml-file according to the SAX mechanism with user-defined callbacks.
Constraints
None
Usage
Public
PVSS managers
UI, CTRL
Parameters
xmlDocumentNameinput, the file-name of the Xml file to be parsed
callBackListinput, the callback functions to be called while parsing
exceptionInfoinout, returns details of any exceptions
Returns
output, 0 on success and -1 if an error during parsing occurred
SAX Callback Mechanism
The callback function-names are passed to the 'fwXml_parseSaxFromFile' function as a PVSS mapping. Three different callbacks are currently implemented which can be activated by associating them to corresponding function-names in the PVSS mapping. The parameter passing of the callback functions follow very closely the Qt-implementation of the 'QXmlContentHandler'. These three types are the following:
Type 'fwXml_StartElement' called when an Xml element-node is encountered.
Activate: 'callBackList[fwXml_StartElement] = "<start-element-callback>";'
Declaration: 'void <start-element-callback> ( string elementName , mapping elementAttributes )'
Type 'fwXml_EndElement' called when an Xml element-node is left (exited).
Activate: 'callBackList[fwXml_EndElement] = "<end-element-callback>";'
Declaration: 'void <end-element-callback> ( string elementName )'
Type 'fwXml_Characters' called when an Xml text-node is encountered.
Activate: 'callBackList[fwXml_Characters] = "<characters-callback>";'
Declaration: 'void <characters-callback> ( string characters )'
A typical example is included in the example-panel "xmlParseSaxFromFileExample.pnl". The Xml-file "xmlExampleSaxParsing.xml" is parsed by the program in this panel. The push-button parses the Xml-file in a pre-order traversal of the element tree and calls the user-defined callbacks on encountering the various node-boundaries.
Reviewed:
2018-07-25 FalsePositive
private void _fwXml_getElementsRecursive ( unsigned  documentId,
int  topNodeId,
string  tagName,
dyn_int &  elements,
dyn_string &  exceptionInfo 
)
'_fwXml_getElementsRecursive' called by 'fwXml_elementsByTagName' and itself in a recursive way.
Constraints
None
Usage
Private
PVSS managers
UI, CTRL
Parameters
documentIdinput, the document identifier
topNodeIdinput, the top node-identifier of the parent or -1 (root-node)
tagNameinput, the tag-name of the children which need to be returned
elementsinout, the elements satisfying the tag-name condition
exceptionInfoinout, returns details of any exceptions
Returns
void
public dyn_int fwXml_elementsByTagName ( unsigned  documentId,
int  topNodeId,
string  tagName,
dyn_string &  exceptionInfo 
)
'fwXml_elementsByTagName' returns all children which have a specific element's tag-name
Constraints
None
Usage
Public
PVSS managers
UI, CTRL
Parameters
documentIdinput, the document identifier
topNodeIdinput, the top node-identifier of the parent or -1 (root-node)
tagNameinput, the tag-name of the children which need to be returned
exceptionInfoinout, returns details of any exceptions
Returns
output, all children which have a specific element's tag-name
Returns a dynamic-integer array containing all descendent elements of this element that are called tag-name. The order they are in the dynamic-integer array is the order they are encountered in a pre-order traversal of the element tree. If '-1' is given to the node-identifier's value, then the whole document is searched.
A typical example is included in the example-panel "xmlElementsByTagNameExample.pnl". The Xml-file "xmlExampleProcessTags.xml" is parsed by the two programs in this panel. The first push-button gets the element-nodes with tagnames 'home', 'room' and 'floor'. The second push-button gets only the element-nodes of the 'room's which are within 'bedrooms's.
How to use...
Note that one needs to load the XML document first into memory and that one may only close the XML document once all manipulations have been finished on the XML nodes of the document.
string xml_full_name, errMsg;
int rtn_code, docum, errLin, errCol;
dyn_string exInfo;
dyn_int elements;
docum = xmlDocumentFromFile ( xml_full_name , errMsg , errLin , errCol );
if ( docum < 0 )
{
DebugN ( "Parsing Error-Message = '" + errMsg + "' Line=" + errLin + " Column=" + errCol );
}
else
{
// Manipulate here the XML nodes of the document
elements = fwXml_elementsByTagName ( docum , ... , exInfo );
rtn_code = xmlCloseDocument ( docum );
DebugN ( "rtn_code = " + rtn_code );
}
public bool fwXml_containsNodeTypes ( int  setOfTypes,
int  requestedTypes 
)
'fwXml_containsNodeTypes'

Checks if the returned contents node-types are all present in the set of requested ones.

Constraints
None
Usage
Public
PVSS managers
UI, CTRL
Parameters
setOfTypesinput, contents node-types to be checked
requestedTypesinput, set of requested node-types that are allowed
Returns
output, boolean, returned contents node-types are all present in the set of requested ones
Reviewed:
2018-07-25 FalsePositive
public int fwXml_childNodesContent ( unsigned  documentId,
int  topNodeId,
dyn_string &  node_names,
dyn_anytype &  attributes,
dyn_string &  nodevalues,
dyn_string &  exceptionInfo 
)
'fwXml_childNodesContent' returns tags, attributes and contained data of all children
Constraints
None
Usage
Public
PVSS managers
UI, CTRL
Parameters
documentIdinput, the document identifier
topNodeIdinput, the top node-identifier of the parent element-node container
node_namesoutput, the node-names or tag-names for element-nodes
attributesoutput, the attributes of element-nodes and added infomation
nodevaluesoutput, the node-values or values of the unique child's text-node
exceptionInfoinout, returns details of any exceptions
Returns
output, the combined types of the type of children which data is returned
When used for simple Xml-file structures
If the function returns 'fwXml_CONTAINS_SIMPLE_ELEMENT_NODES', then the child-nodes are all element-nodes which contain at most one text-node as their child. The following is returned via the three output-parameters: 'node_names' returns the tag-names of the element-nodes, 'attributes' returns all the attributes of the element-nodes, 'nodevalues' returns the value (character-data) of the contained text-node if present, otherwise it returns the empty string.
A typical example is included in the example-panel "xmlChildNodesContentExample.pnl" (first push-button). The Xml-file "xmlExampleFlatListing.xml" can be completely read by issuing one single call to this function - specify for the 'node' variable the node-identifier of the element-node called "<room>".
Note that this function was created especially for users who want to parse Xml-files of a structure which corresponds to the above description. Only read further if you want to use this function to parse more complex Xml-file structures.
When used for complex Xml-file structures
If any of the child-nodes is different from an element-node which contains at most one text-node as its child, then the return-code will be different from 'fwXml_CONTAINS_SIMPLE_ELEMENT_NODES' [and will be more specific the bitwise OR-ed values which are obtained by shifting the value '1' to the left by a number of places which corresponds to the internal enumerated value of the node-type].
An example will illustrate this much easier. Refer again to the example-panel "xmlChildNodesContentExample.pnl" (second push-button). The Xml-file corresponds this time to "xmlExampleGreatText.xml". In this example there is in addition to the above at least one text-node as a direct child (not as a child of an element-node). In that case, the return-code is 'fwXml_CONTAINS_TEXT_NODES' [this is obtained by shifting '1' to the left by XML_TEXT_NODE places (1<<XML_TEXT_NODE) [1<<3]].
For nodes which are not element-nodes, the returned values are: 'node_names' returns the node-name of the node as queried by 'xmlNodeName', 'attributes' returns a single mapping "[fwXml_CHILDNODESTYPE;(int)<node-type>]" which indicates the node-type of the node, 'nodevalues' returns the node-value of the node as queried by 'xmlNodeValue'.
If there is additionally at least one child-node with more than one child or with a child which is not a text-node then the return-code will have the bit-value '2' also set. The same example-panel "xmlChildNodesContentExample.pnl" illustrates this. Third button parses the "xmlExampleHierarchical.xml" Xml-file - return-code corresponds to 'fwXml_CONTAINS_COMPLEX_ELEMENT_NODES' [(1<<XML_ELEMENT_NODE) [1<<1]]. Fourth button parses the Xml-file "xmlExampleMoreComplex.xml" - return-code corresponds to 'fwXml_CONTAINS_COMPLEX_ELEMENT_NODES | fwXml_CONTAINS_TEXT_NODES' [obtained by bitwise OR-ing of (1<<XML_ELEMENT_NODE) and (1<<XML_TEXT_NODE) which is [(1<<1)|(1<<3)]].
For element-nodes with more than one child or with a child which is not a text-node, the returned values are: 'node_names' returns the tag-name of the node, 'attributes' returns all the attributes of the element-nodes with additionally the two following added mappings "[fwXml_CHILDNODESTYPE;(int)XML_ELEMENT_NODE]" which is the node-type and "[fwXml_CHILDSUBTREEID;(int)<element-node-identifier>]", 'nodevalues' returns the empty string.
How to use...
Note that one needs to load the XML document first into memory and that one may only close the XML document once all manipulations have been finished on the XML nodes of the document.
string xml_full_name, errMsg;
int rtn_code, docum, nodeIdentifier, errLin, errCol;
dyn_string exInfo;
docum = xmlDocumentFromFile ( xml_full_name , errMsg , errLin , errCol );
if ( docum < 0 )
{
DebugN ( "Parsing Error-Message = '" + errMsg + "' Line=" + errLin + " Column=" + errCol );
}
else
{
// Search first for the XML element node one is interested in...
rtn_code = fwXml_childNodesContent ( docum , nodeIdentifier , ... , exInfo );
rtn_code = xmlCloseDocument ( docum );
}
public int fwXml_appendChildContent ( unsigned  documentId,
int  topNodeId,
dyn_string  node_names,
dyn_anytype  attributes,
dyn_string  nodevalues,
dyn_string &  exceptionInfo 
)
'fwXml_appendChildContent' appends element-nodes, attributes and contained data to the Xml Tree
Constraints
None
Usage
Public
PVSS managers
UI, CTRL
Parameters
documentIdinput, the document identifier
topNodeIdinput, the top node-identifier of the parent element-node container
node_namesinput, tag-names for element-nodes
attributesinput, the attributes of element-nodes
nodevaluesinput, the values of the unique child's text-node
exceptionInfoinout, returns details of any exceptions
Returns
output, 0 on success and -1 if an error during construction occurred
Used for simple and more complex Xml-file structures
This function constructs underneath the given node an ordered list of children element-nodes, or other types of nodes like: text-nodes, cdata-section nodes or comment nodes. Each of these children element-nodes gets their corresponding attributes and if defined and not the empty-string their corresponding child text-node.
A typical example is included in the example-panel "xmlCreateChildContentExample.pnl". The first push-button creates a list of element-nodes. The second push-button creates a list of element-nodes with most of them having a unique child's text-node. The third push-button creates a list of element-nodes with some of them having one or more qualifying attributes. The fourth push-button combines all the above examples together and creates a list of element-nodes with some of them attributes and most of them a unique child's text-node. The fifth push-button shows you how to add more exotic elements like text-nodes, cdata-section nodes and comment nodes.
Reviewed:
2018-07-25 FalsePositive

Variable Documentation

private const int fwXml_PARSING_DOWNORACROSS = 0
fwXml_PARSING_DOWNORACROSS

Constant used in calculating the type of 'callback' that needs to be executed! This directive specifiy the 'callbacks' to be executed when parsing down or across for leave-nodes.

private const int fwXml_PARSING_WHEN_LEAVING = 1
fwXml_PARSING_DOWNORACROSS

Constant used in calculating the type of 'callback' that needs to be executed! This directive specifiy the 'callbacks' to be executed when parsing up, which means leaving the node.

const int fwXml_SAXSTARTELEMENT = 2
fwXml_SAXSTARTELEMENT

Constant used in the mapping that associates the user-defined callback to the start of an Xml element-node

const int fwXml_SAXENDELEMENT = 3
fwXml_SAXENDELEMENT

Constant used in the mapping that associates the user-defined callback to the end of an Xml element-node

const int fwXml_SAXTEXT = 6
fwXml_SAXTEXT

Constant used in the mapping that associates the user-defined callback to an Xml text-node

const int fwXml_CONTAINS_SIMPLE_ELEMENT_NODES = 0
fwXml_CONTAINS_SIMPLE_ELEMENT_NODES

The constants used to check the return-code of the 'fwXml_childNodesContent' function. One needs to OR those flags together and pass it as the 'requestedTypes' parameter in the call to 'fwXml_containsNodeTypes'. The return-value of the function 'fwXml_childNodesContent' is then passed as the 'setOfTypes' parameter in the same call to 'fwXml_containsNodeTypes'.

const int fwXml_CONTAINS_TEXT_NODES = 8
fwXml_CONTAINS_TEXT_NODES

The constants used to check the return-code of the 'fwXml_childNodesContent' function. One needs to OR those flags together and pass it as the 'requestedTypes' parameter in the call to 'fwXml_containsNodeTypes'. The return-value of the function 'fwXml_childNodesContent' is then passed as the 'setOfTypes' parameter in the same call to 'fwXml_containsNodeTypes'.

const int fwXml_CONTAINS_COMMENT_NODES = 256
fwXml_CONTAINS_COMMENT_NODES

The constants used to check the return-code of the 'fwXml_childNodesContent' function. One needs to OR those flags together and pass it as the 'requestedTypes' parameter in the call to 'fwXml_containsNodeTypes'. The return-value of the function 'fwXml_childNodesContent' is then passed as the 'setOfTypes' parameter in the same call to 'fwXml_containsNodeTypes'.

const int fwXml_CONTAINS_COMPLEX_ELEMENT_NODES = 2
fwXml_CONTAINS_COMPLEX_ELEMENT_NODES

The constants used to check the return-code of the 'fwXml_childNodesContent' function. One needs to OR those flags together and pass it as the 'requestedTypes' parameter in the call to 'fwXml_containsNodeTypes'. The return-value of the function 'fwXml_childNodesContent' is then passed as the 'setOfTypes' parameter in the same call to 'fwXml_containsNodeTypes'.

const string fwXml_CHILDNODESTYPE = "fwXml_ChildNodesType"
fwXml_CHILDNODESTYPE

Constant used in the mapping that identifies the node-type of the node in question

const string fwXml_CHILDSUBTREEID = "fwXml_ChildSubTreeId"
fwXml_CHILDSUBTREEID

Constant used in the mapping that identifies the node-identifier of the node in question