fwXML.ctl File Reference



const int fwXml_SAXSTARTELEMENT = 2
const int fwXml_SAXENDELEMENT = 3
const int fwXml_SAXCHARACTERS = 6
const string fwXml_CHILDNODESTYPE = "fwXml_ChildNodesType"
const string fwXml_CHILDSUBTREEID = "fwXml_ChildSubTreeId"
public string fwXml_trim (string value)
private void _fwXml_parseSaxRecursive (int document, mapping callBacks, int level, int nodes_id, dyn_string &exceptionInfo)
public int fwXml_parseSaxFromFile (string xml_file, mapping callBacks, string &errMsg, string &errLin, string &errCol, dyn_string &exceptionInfo)
void _fwXml_elementsRecursive (unsigned doc, int node, string tag, dyn_int &elements, dyn_string &exceptionInfo)
dyn_int fwXml_elementsByTagName (unsigned doc, int node, string tag, dyn_string &exceptionInfo)
int fwXml_childNodesContent (unsigned doc, int node, dyn_string &node_names, dyn_anytype &attributes, dyn_string &nodevalues, dyn_string &exceptionInfo)
int fwXml_appendChildContent (unsigned doc, int node, 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
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:
Daniel Davids (IT-CO)

Function Documentation

void _fwXml_elementsRecursive ( unsigned  doc,
int  node,
string  tag,
dyn_int &  elements,
dyn_string &  exceptionInfo 
)

'_fwXml_elementsRecursive' called by '' and itself in a recursive way.

Constraints
None
Usage
Private
PVSS managers
UI, CTRL
Parameters:
doc input, the document identifier
node input, the node identifier of the parent or -1 (root-node)
tag input, the tag-name of the children which need to be returned
elements inout, the elements satisfying the tag-name condition
exceptionInfo inout, returns details of any exceptions
Returns:
void

Referenced by fwXml_elementsByTagName().

private void _fwXml_parseSaxRecursive ( int  document,
mapping  callBacks,
int  level,
int  nodes_id,
dyn_string &  exceptionInfo 
)

'_fwXml_parseSaxRecursive' called by 'fwXml_parseSaxFromFile' and itself in a recursive way.

Constraints
None
Usage
Private
PVSS managers
UI, CTRL
Parameters:
document input, the document-ident of the loaded Xml file
callBacks input, the callback functions to be called while parsing
level input, the current nesting-level of the recursive calls
nodes_id input, the node-ident from which the sub-tree is parsed
exceptionInfo inout, returns details of any exceptions
Returns:
void

References fwXml_SAXCHARACTERS, fwXml_SAXENDELEMENT, and fwXml_SAXSTARTELEMENT.

Referenced by fwXml_parseSaxFromFile().

int fwXml_appendChildContent ( unsigned  doc,
int  node,
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:
doc input, the document identifier
node input, the node identifier of the parent element-node container
node_names input, tag-names for element-nodes
attributes input, the attributes of element-nodes
nodevalues input, the values of the unique child's text-node
exceptionInfo inout, 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.

References fwXml_CHILDNODESTYPE.

int fwXml_childNodesContent ( unsigned  doc,
int  node,
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:
doc input, the document identifier
node input, the node identifier of the parent element-node container
node_names output, the node-names or tag-names for element-nodes
attributes output, the attributes of element-nodes and added infomation
nodevalues output, the node-values or values of the unique child's text-node
exceptionInfo inout, 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 '0' (zero), 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 '0' 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 '8' - 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 '2' (1<<XML_ELEMENT_NODE) [1<<1]. Fourth button parses the Xml-file "xmlExampleMoreComplex.xml" - return-code corresponds to '10' - 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.

References fwXml_CHILDNODESTYPE, and fwXml_CHILDSUBTREEID.

dyn_int fwXml_elementsByTagName ( unsigned  doc,
int  node,
string  tag,
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:
doc input, the document identifier
node input, the node identifier of the parent or -1 (root-node)
tag input, the tag-name of the children which need to be returned
exceptionInfo inout, 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.

References _fwXml_elementsRecursive().

public int fwXml_parseSaxFromFile ( string  xml_file,
mapping  callBacks,
string &  errMsg,
string &  errLin,
string &  errCol,
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:
xml_file input, the file-name of the Xml file to be parsed
callBacks input, the callback functions to be called while parsing
errMsg output, the error message if the Xml file cannot be parsed
errLin output, the line in the Xml file at which the error occurred
errCol output, the column in the Xml file at which the error occurred
exceptionInfo inout, 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: 'callBacks[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: 'callBacks[fwXml_EndElement] = "<end-element-callback>";'
Declaration: 'void <end-element-callback> ( string elementName )'
Type 'fwXml_Characters' called when an Xml text-node is encountered.
Activate: 'callBacks[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.

References _fwXml_parseSaxRecursive().

public string fwXml_trim ( string  value  ) 

'fwXml_trim' to trim a string, especially to be used for trimming an Xml-Node's value.

Constraints
None
Usage
Public
PVSS managers
UI, CTRL
Parameters:
value inout, the value to be trimmed
Returns:
output, the trimmed value

Variable Documentation

const string fwXml_CHILDNODESTYPE = "fwXml_ChildNodesType"

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

Referenced by fwXml_appendChildContent(), and fwXml_childNodesContent().

const string fwXml_CHILDSUBTREEID = "fwXml_ChildSubTreeId"

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

Referenced by fwXml_childNodesContent().

const int fwXml_SAXCHARACTERS = 6

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

Referenced by _fwXml_parseSaxRecursive().

const int fwXml_SAXENDELEMENT = 3

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

Referenced by _fwXml_parseSaxRecursive().

const int fwXml_SAXSTARTELEMENT = 2

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

Referenced by _fwXml_parseSaxRecursive().


Generated on 19 Aug 2013 by  doxygen 1.6.1