Document Information

A publication of

SSA Global
500 West Madison
Suite 1600
Chicago, IL 60661
USA

Copyright(c) 2004 Baan International B.V., a subsidiary of SSA Global Technologies, Inc.
All rights reserved.

The information in this document is subject to change without notice. No part of this document may be reproduced, stored or transmitted in any form or by any mechanical, for any purpose, without the express written permission of SSA Global

SSA Global assumes no liability for any damages incurred, directly or indirectly, from any errors, omissions or discrepancies between the software and the information contained in this document.

Document Information

Code: | H1004 EN-US (only the XML object part)
Group: | Development Help
Build: | BDUX16611
Build date: | November 26, 2004


Welcome

The SSA ERP LN Programmers Guide provides the latest information about the SSA ERP LN 3GL and 4GL programming languages, including reference material and in-depth articles on several aspects of design and development. You can navigate via content listings or use the index to look up keywords. Via the search page you can enter specific queries.

Note: This specific version of the Programmer's Guide only contains the XML object functions, and is applicable to the current versions of the SSA BaanIVc4, SSA BaanERP 5.0c, and SSA ERP LN 6.1 products.

Send Us Your Feedback


XML object overview

The purpose of this document is to define the functional requirements for the XML object. The XML object is an extension of the Baan VM allowing a 3GL/4GL application to exchange structured data using the XML format.

Environment

The XML object functionality is integrated into the Baan VM. It is accessible by 3GL/4GL programs using a set of Baan 3GL functions. The XML object is applied by CMF for communication between a messaging service and a 4GL application. The XML object is also applied by B3 for constructing and exploring communication objects. The XML object functionality is not restricted to CMF and B3 but may be used by other applications that want to exchange structured data using the XML format.

Architecture

The architecture of the XML object functionality is shown the following picture:
XML Object Architecture

References

[XMLSTD] | Extensible Markup Language 1.0, W3C Recommendation, February 10, 1998: http://www.w3.org/TR/1998/REC-xml-19980210 and October 6, 2000: http://www.w3.org/TR/2000/REC-xml-20001006.
[EXPAT] | Expat is an XML1.0 parser written in C written by James Clark. Source code and information can be found at: http://www.jclark.com/xml/expat.html
[CMFDS] | Common Message Facility, Definition study, Doc.Nr: D0525 US

In this figure, the following components are shown:

  • XML Object API. A set of 3GL functions available to a 3GL/4GL application to access an XML Object.
  • XML Object. Baan VM in-memory structure closely representing the structure of an XML document.
  • XML Parser. The XML object component which function is to convert an XML document into an XML object.
  • XML generator. The XML object component which function is to convert an XML object into an XML document.

User characteristics

The direct users of the XML object are application programmers using the XML Object API. Users of CMF and B3 use the XML object implicitly.

Future extensions

A possible future extension is the option of using a validating parser.

Performance requirements

The XML parser implementation used as a basis for the XML object has been optimized for performance.

Software system attributes

The approximate size of this component is about 7K lines of C code.

The XML parser is based on James's Clark free minimal XML parser written in C: "expat". See [EXPAT] for source and description.

Naming convention: all XML object functions start with the prefix: "xml".

The following implementation decisions are made:

  • The XML functions is built as a library in /logic/lib/xml.
  • Conversion from TSS to UTF-8 and vice-versa are built-in.
  • Source code conforms to ANSI-C.

Related topics

  • Constraints
  • Glossary
  • Synopsis
  • API


XML object constraints

The XML object is not meant to implement a full XML parser/generator for building advanced XML document processing applications. The purpose of the XML object is to allow 3GL/4GL applications to exchange structured data using the XML format. Therefore not the complete XML standard is supported by the parser/generator, but only the sub-set needed to meet its requirement. Below a list of restrictions with respect to [XMLSTD] is given. This section should be read in conjunction with [XMLSTD]. All references to XML production rules in the [XMLSTD] are represented in italic.

XML generator restrictions

  • A fixed XMLDecl is generated. This declaration is always: <?xml version="1.0"?>
  • For generation of doctypedecl contents (e.g. markupdecl and PEReference ) no XML tag generation support is given. Correct formatting of this contents is left to the application.
  • For element content other than element and PI (e.g. Chardata, Reference, CDSect, Comment) no XML tag generation support is given. Correct formatting of this content is left to the application.
  • The output encoding is always UTF-8.
  • A complete XML object must be constructed in Baan VM memory, before an XML document can be generated from it.

XML parser restrictions

  • The XML parser does not validate the document against its DTD. It only performs the well-formedness checks.
  • The application does not have access to the document type definition (DTD).
  • Default values for attributes defined in an external DTD are not passed to the application only default values defined in internal DTD sections are passed to the application.
  • References to external parsed general entities are not processed by the parser but are ignored. So documents consisting out of multiple entities (modules) are not supported. References to internal entities are expanded before they are passed to the application.
  • References to (external) unparsed entities (binary data) are ignored.
  • The following document encodings are supported:
    • UTF-8
    • UTF-16 (unicode)
    • ISO-8859-1
  • Parsing of a document stops when an error is encountered.
  • Only parsing of a complete XML document is supported, resulting in a complete XML object in Baan VM memory.
  • A maximum XML element nesting depth of 256 is allowed.

Related topics

  • Overview
  • Glossary
  • API


XML object glossary

XML | EXtensible Markup Language.
B3 | Baan Business Bus
DTD | Document Type Definition, a specific definition that follows the rules of the Standard Generalized Markup Language (SGML). A DTD is a specification that accompanies a document and identifies what the codes (or markup) are that separate paragraphs, identify topic headings, and so forth, and indicate how each must be processed. By mailing a DTD with a document, any location that has a DTD reader (or SGML compiler) can process the document and display or print it as intended.
CMF | Common Messaging Facility
Node | In a network, a node is a connection point, either a redistribution point or an end point for data transmissions. In general, a node has programmed or engineered capability to recognize and process or forward transmissions to other nodes.
Parser | A program, usually part of a compiler, that receives input in the form of sequential source program instructions, interactive online commands, markup tags, or some other defined interface. The parser then breaks this input into parts (for example, the nouns (objects), verbs (methods), and their attributes or options) that can then be managed by other programs (for example, other components in a compiler). A parser may also check to see whether all necessary input has been provided.
TSS | Triton Super Set

Related topics

  • Overview
  • Constraints
  • API


XML object synopsis

3GL/4GL function | XML library function
Verify the used characters | long xmlContainsValidCharactersOnly(string inputstring) | int xmlContainsValidTssCharactersOnly(const char * aTss);
Serialize XML Object long xmlWrite(long fp, long fromNode, [long toNode] )
long xmlWritePretty(long fp, long fromNode, [long toNode] )
long xmlWriteToString(ref string buffer, long fromNode, [long toNode] )
long xmlWritePrettyToString(ref string buffer, long fromNode, [long toNode] )
string xmlString$(long fromNode, [long toNode] )
string xmlPrettyString$(long fromNode, [long toNode] )
long xmlAllocString(ref string basedString(), long fromNode, [long toNode] )
long xmlAllocPrettyString(ref string basedString(), long fromNode, [long toNode] ) 		int xmlWrite(STREAM *fp, XmlNodePointer pFrom, XmlNodePointer pTo, int prettyPrint);
int xmlWriteBuffer(char *buffer, unsigned long bufferSize, XmlNodePointer pFrom, XmlNodePointer pTo, int prettyPrint);
int xmlWriteBufferExt(char *buffer, unsigned long bufferSize, XmlNodePointer pFrom, XmlNodePointer pTo, int prettyPrint);
Get length of a serialized XML Object long xmlGetStringLength(long fromNode, [long toNode] )
long xmlGetPrettyStringLength(long fromNode, [long toNode] ) 		int xmlWriteBufferExt(char *buffer, unsigned long bufferSize, XmlNodePointer pFrom, XmlNodePointer pTo, int prettyPrint);
De-serialize XML Object long xmlRead(long fp, ref string error, [ long whitespacehandling ] )
long xmlReadFromString(string xmlString, ref string error, [ long whitespacehandling ] ) 		XmlNodePointer xmlRead(STREAM *fp, char *parserError, XmlContextPointer pContext);
XmlNodePointer xmlReadExt(STREAM *fp, char *parserError, XmlWhiteSpaceHandling whiteSpaceHandling, XmlContextPointer pContext);
XmlNodePointer xmlReadBuffer(char *buffer, unsigned long bufferSize, char *parserError, XmlContextPointer pContext);
XmlNodePointer xmlReadBufferExt(char *buffer, unsigned long bufferSize,char * parserError, XmlWhiteSpaceHandling whiteSpaceHandling, XmlContextPointer pContext);
Create a new Node | long xmlNewNode(string name, [long type, long parentNode ]) | XmlNodePointer xmlNewNode(char *name, XmlNodePointer _pParent, XmlContextPointer pContext, int nodeType);
Create an Element Node with Data Node | long xmlNewDataElement(string name, string data, [ long parentNode ]) | XmlNodePointer xmlNewDataElement(char *name, char *data, XmlNodePointer _pParent, XmlContextPointer pContext);
Rewrite Data Element | long xmlRewriteDataElement(long node, string name, string data) | int xmlRewriteDataElement(XmlNodePointer _pNode, char *name, char *data, XmlContextPointer pContext);
Get data of all Elements long xmlGetDataElement(long node, string name, ref string data)
string xmlDataElement$(long node, string name, [ string default.value ] )
long xmlAllocDataElement(ref string basedString(), long node, string name, [ string default.value ] ) 		int xmlGetDataElement(XmlNodePointer _pNode, char *name, char *data, int sizeOfData);
int xmlGetDataElementLength(XmlNodePointer _pNode, char *name);
Get data length of all Elements | long xmlGetDataElementLength(long node, string name) | int xmlGetDataElementLength(XmlNodePointer _pNode, char *name);
Set name of a Node | long xmlSetName(long node, string name) | int xmlSetName(XmlNodePointer _pNode, char *name, XmlContextPointer pContext);
Set data of a Node | long xmlSetData(long node, string data) | int xmlSetData(XmlNodePointer _pNode, char *data, XmlContextPointer pContext);
Set attribute | long xmlSetAttribute(long node, string attributeName, string data) | int xmlSetAttribute(XmlNodePointer _pNode, char *name, char *data, XmlContextPointer pContext);
Delete attribute | long xmlDeleteAttribute(long node, string attribute ) | int xmlDeleteAttribute(XmlNodePointer _pNode, char *name, XmlContextPointer pContext);
Get name of a Node long xmlGetName(long node, ref string name)
string xmlName$(long node, [ string default.value ] )
long xmlAllocName(ref string basedString(), long node, [ string default.value ] ) 		int xmlGetName(XmlNodePointer _pNode, char *name, int sizeOfName);
char *xmlGetNameValue(XmlNodePointer _pNode);
Get name length of a Node | long xmlGetNameLength(long node) | char *xmlGetNameValue(XmlNodePointer _pNode);
Get parent of a Node | long xmlGetParent(long node) | XmlNodePointer xmlGetParent(XmlNodePointer _pNode);
Get child of a Node long xmlGetFirstChild(long node)
long xmlGetLastChild(long node) 		XmlNodePointer xmlGetFChild(XmlNodePointer _pNode);
XmlNodePointer xmlGetLChild(XmlNodePointer _pNode);
Get number of child Nodes | long xmlGetNumChilds(long node) | int xmlGetNumChilds(XmlNodePointer _pNode);
Get sibling of a Node long xmlGetRightSibling(long node)
long xmlGetLeftSibling(long node) 		XmlNodePointer xmlGetRSib(XmlNodePointer _pNode);
XmlNodePointer xmlGetLSib(XmlNodePointer _pNode);
Get number of sibling Nodes long xmlGetNumSiblings(long node)
long xmlGetNumRightSiblings(long node)
long xmlGetNumLeftSiblings(long node) 		int xmlGetNumSib(XmlNodePointer _pNode);
int xmlGetNumRSib(XmlNodePointer _pNode);
int xmlGetNumLSib(XmlNodePointer _pNode);
Get data of a Node long xmlGetData(long node, ref string data)
string xmlData$(long node, [ string default.value ] )
long xmlAllocData(ref string basedString(), long node, [ string default.value ] ) 		int xmlGetData(XmlNodePointer _pNode, char *data, int sizeOfData);
int xmlGetDataLength(XmlNodePointer _pNode);
Get data length of a Node | long xmlGetDataLength(long node) | int xmlGetDataLength(XmlNodePointer _pNode);
Get attribute value long xmlGetAttribute(long node, string attributeName, ref string data)
string xmlAttribute$(long node, string attributeName, [ string default.value ] )
long xmlAllocAttribute(ref string basedString(), long node, string attributeName, [ string default.value ] ) 		int xmlGetAttribute(XmlNodePointer _pNode, char *name, char *data, int sizeOfData);
char *xmlGetAttributeValue(XmlNodePointer _pNode, char *name);
Get attribute length | long xmlGetAttributeLength(long node, string attributeName) | char *xmlGetAttributeValue(XmlNodePointer _pNode, char *name);
Get attribute name long xmlGetAttributeName(long node, long attributeNr, ref string attributeName)
string xmlAttributeName$(long node, long attributeNr, [ string default.value ] )
long xmlAllocAttributeName(ref string basedString(), long node, long attributeNr,[ string default.value ] ) 		int xmlGetAttributeName(XmlNodePointer _pNode, int index, char *name, int sizeOfName);
char *xmlGetAttributeNameValue(XmlNodePointer _pNode, int index);
Get attribute name length | long xmlGetAttributeNameLength(long node, long attributeNr) | char *xmlGetAttributeNameValue(XmlNodePointer _pNode, int index);
Get number of attributes | long xmlGetNumAttributes(long node) | int xmlGetNumAttributes(XmlNodePointer _pNode);
Get Node type | long xmlGetType(long node) | int xmlGetType(XmlNodePointer _pNode);
Delete Nodes | long xmlDelete(long fromNode, [ long toNode ]) | int xmlDeleteList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlContextPointer pContext);
Unlink Nodes | long xmlUnlink(long fromNode, [ long toNode ]) | XmlNodePointer xmlMoveList(XmlNodePointer _pFrom, XmlNodePointer _pTo);
Unlink and Insert Nodes | long xmlInsert(long destinationNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlMoveListAndInsert(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);
Unlink and Add Nodes | long xmlAdd(long destinationNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlMoveListAndAdd(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);
Unlink and Append Nodes | long xmlAppend(long destinationNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlMoveListAndAppend(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);
Unlink and Insert Nodes in Children | long xmlInsertInChilds(long parentNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlMoveListAndInsertInChildList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);
Unlink and Append Nodes to Children | long xmlAppendToChilds(long parentNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlMoveListAndAppendToChildList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);
Duplicate Nodes | long xmlDuplicate(long fromNode, [ long toNode ]) | XmlNodePointer xmlDupList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlContextPointer pContext);
Duplicate Nodes to Process | long xmlDuplicateToProcess(long processId, long fromNode, [ long toNode ]) | XmlNodePointer xmlDupList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlContextPointer pContext);
Duplicate and Insert Nodes | long xmlDuplicateAndInsert(long destinationNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlDupListAndInsert(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);
Duplicate and Add Nodes | long xmlDuplicateAndAdd(long destinationNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlDupListAndAdd(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);
Duplicate and Append Nodes | long xmlDuplicateAndAppend(long destinationNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlDupListAndAppend(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);
Duplicate and Insert Nodes in Children | long xmlDuplicateAndInsertInChilds(long parentNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlDupListAndInsertInChildList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);
Duplicate and Append Nodes to Children | long xmlDuplicateAndAppendToChilds(long parentNode, long fromNode, [ long toNode ]) | XmlNodePointer xmlDupListAndAppendToChildList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);
Find first Node | long xmlFindFirst(string tagName, long fromNode, [ long toNode ]) | XmlNodePointer xmlFindFirstInList(XmlNodePointer _pFrom, XmlNodePointer _pTo, char *criteria);
Find first Node using a Match Pattern | long xmlFindFirstMatch(string pattern, long fromNode, [ long toNode ]) | XmlNodePointer xmlFindFirstMatchInList(XmlNodePointer _pFrom, XmlNodePointer _pTo, char *pPattern);
Find Nodes | long xmlFindNodes(long node, string criteria, long maxFound, [ref long numFound] ) | XmlNodePointer xmlFindNodes(XmlNodePointer _pNode, char *criteria, int maxFound, int *pNumFound, XmlContextPointer pContext)
Find Nodes using a Match Pattern | long xmlFindMatch(string pattern, long fromNode, [ long toNode ]) | XmlNodePointer xmlFindMatchInList(XmlNodePointer _pFrom, XmlNodePointer _pTo, char *pPattern, XmlContextPointer pContext);
Find set of Sibling Nodes | long xmlFindSetOfSiblingNodes(long node, string criteria, long maxFound, [ref long numFound]) | XmlNodePointer xmlFindSetOfSiblingNodes(XmlNodePointer _pNode, char *criteria, int maxFound, int *pNumFound, XmlContextPointer pContext)
Create context | No 3GL/4GL function | XmlContextPointer xmlCreateContext(long mid);
Delete context | No 3GL/4GL function | void xmlDeleteContext(XmlContextPointer pContext);

Related topics

  • Overview
  • Constraints
  • Glossary
  • API


XML object API

The XML Object API defines the functions that can be used by any 3GL/4GL application to create, access and destroy an XML object.

Object structure

  • A node which describes an XML element (XML_ELEMENT).
  • A node which describes an XML DTD (XML_DTD).
  • A node which describes an XML data item (XML_DATA). n
  • A node which describes an XML Processing Instruction (XML_PI).

Nodes of type XML_ELEMENT and XML_DTD can be nodes or leaves in the tree. So nodes of these types can have child nodes. Furthermore nodes of these two types can have a list of attributes. An Attribute is always a name-value pair.

Nodes of type XML_DATA and XML_PI are always leaf nodes and can thus not have any child nodes.

Below a sample XML document is shown. In Figure 1 the corresponding XML Object tree is shown.

<?xml version="1.0"?>
<!DOCTYPE CMF SYSTEM "cmf1.dtd">
<CMF>
        <IDENTIFICATION
                MESSAGE-ID="34a98u0erirori"
                CLASS="order"
                SUBJECT="Subject string"
        />
        <RECIPIENTS>
                <FROM
                        NAME="Jan Jansen"
                        TYPE="SMTP"
                        ADDRESS="jjansen@example.com"
                />
         </RECIPIENTS>
        <MESSAGE>The message text
</CMF>

Figure 1 - XML Object tree corresponding with sample XML document

The XML functions access these nodes using unique id's. These id's are unique within the scope of one instantiation of a Baan VM. So these id's can be handed over to another 3GL processes running inside the same Baan VM but cannot be passed to a process running in another Baan VM.

Multi-process issues

For passing XML nodes to other Baan VM processes, the following restrictions apply:

  • There is always one owner process of an XML tree.
  • Only the owner process is allowed to change or delete (parts of) an XML tree. Other processes in the same Baan VM only have read access.
  • When the process, which is an owner of an XML tree, exits, the XML tree is implicitly deleted. This means that other processes, which might still have a reference to this tree, are not allowed to use this reference anymore.
  • A process becomes the owner of an XML tree by calling one of the following functions:
    • xmlRead()
    • xmlReadFromString()
    • xmlNewNode()
    • xmlNewDataElement()
    • xmlRewriteDataElement()
    • xmlDuplicate()
    • xmlDuplicateAndInsert()
    • xmlDuplicateAndAppend()
    • xmlDuplicateAndInsertInChilds()
    • xmlDuplicateAndAppendtoChilds()
    • xmlDuplicateToProcess() (with own pid as argument).
  • A process can transfer owner ship of a copy of an XML tree to another 3GL process by using xmlDuplicateToProcess() with passing the pid of the 3GL process which becomes the owner of this newly created XML tree.

White-space handling

When parsing a document, white space is handled in one of three ways, depending on the value of the whitespacehandling argument of xmlRead or xmlReadFromString and on the value of the xml:space attribute. Allowed values for this argument are XmlWhiteSpaceLegacyMode, XmlPreserveWhiteSpace, and XmlReplaceWhiteSpaceBySingleSpace. For a detailed description of the meaning of these values, see De-serialize XML Object.

Character Data escaping

According to [XMLSTD], the ampersand character (&) and the left angle bracket (<) may not appear in element content data nor in attribute values. Furthermore an attribute value may not contain any double-quote character ("). If these characters are needed, they must be escaped using either numeric character references or the strings &amp;, &lt; and &quot; respectively. The XML parser replaces these escape strings with the corresponding literal representation. The XML generator escapes the ampersand, left angle bracket and double-quote characters in node content and attribute values before serializing this to the output stream. This relieves applications from checking the data for these characters.

Allowed characters

According to [XMLSTD], the following Unicode characters are allowed in an XML document:

    Char ::=  #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
All other characters are forbidden. There is no possibility to escape them. The forbidden characters are:
  • ASCII control characters in the range [#x0-#x1F], except the allowed characters #x9 (Horizontal Tab), #xA (Line Feed), and #xD (Carriage Return);
  • Unicode surrogate characters in the range [#xD800-#xDFFF];
  • The <not a character> Unicode values #xFFFE and #xFFFF.
The XML generator verifies that no forbidden characters are produced. When a forbidden character is encountered, the serialization is stopped and an error is returned.
It can be checked beforehand whether a string (after conversion from TSS to UTF-8) contains valid characters only. See xmlContainsValidCharactersOnly.

Handling of fromNode and toNode arguments

Several xml functions take as arguments long fromNode,[long toNode]. These arguments are references to XML nodes on which the operation must be performed. This includes all children of these nodes.

When only fromNode is specified, the operation is performed on the tree for which fromNode is the top node. The default tree traversal order is depth first. In this order the tree is traversed starting at the top node followed by the first (left most) child. See Figure 2 for an example of the depth first traversal order. The traversal order in this tree corresponds with the attribute order value. In some cases a breadth first traversal order is used. See Figure 3 for an example.

When fromNode and toNode are specified, the operation is performed on all nodes starting at fromNode and all right siblings of fromNode up to and including toNode.

When fromNode and toNode are specified and toNode has a value of zero, the operation is performed on all nodes starting at fromNode and all right siblings of fromNode up to and including the last node in the list.

When fromNode and toNode are specified and fromNode has a value of zero, fromNode is treated as the beginning of a list. The operation is then performed on all nodes starting at the beginning of the list up to and including the node referenced by toNode.

Figure 2 - Depth first Tree traversal order

Figure 3 - Breadth first Tree traversal order

Related topics

  • Overview
  • Constraints
  • Glossary


Doctype element in relation to XML

The optional document type element (created with function xmlNewNode("name", XML_DTD) ) can be used to generate an XML-document with a DTD. When an XML object results from parsing an XML document, no document type (XML_DTD) node is created.

For the document type element of an XML object the following mapping rules apply:

  • The name of the XML_DTD node is the name of the document type definition.
  • The value of the optional attribute "NAMEURL" is the value of the XML expression SystemLiteral part of the XML expression ExternalID .
  • The value of the optional attribute "NAMEPUBLICID" is the value of the XML expression PubidLiteral part of the XML expression ExternalID. When attribute "NAMEURL" is defined and attribute "NAMEPUBLICID" is not defined, the XML expression ExternalID gets the form: "SYSTEM SystemLiteral. When both attributes are defined, the XML expression ExternalID gets the form: "PUBLIC PubidLiteral SystemLiteral"
  • No child nodes other than XML_DATA or XML_PI are allowed for a XML_DTD node.
  • When data is added to a XML_DTD node, this is written as-is to the XML document. The generator does not generate XML tags for the declarations.

Related topics

  • Overview


Example XML generation

Below a piece of Baan-C code is shown for generating an XML document. For ease of reading, no checking on the return codes of the functions is done.

long    cmfId, identId, recipientsId, fromId, dtdId
long    fd, retVal

|Create the doctype element and populate its contents
dtdId = xmlNewNode("CMF", XML_DTD)
retVal = xmlsetAttribute(dtdId,  "NAMEURL", "cmf1.dtd")

|Create the root element and make it a right sibling of the XML_DTD node.
cmfId = xmlNewNode("CMF" )
retVal = xmlAdd(dtdId, cmfId )

|Create IDENTIFICATION element and add its attributes
identId = xmlNewNode("IDENTIFICATION", XML_ELEMENT, cmfId)

retVal = xmlSetAttribute (identId,  "MESSAGE-ID", "34a98u0erirori" )
retVal = xmlSetAttribute(identId,   "CLASS", "order" )
retVal = xmlSetAttribute(identId,   "SUBJECT", "Subject string" )

|Create RECIPIENTS element
recipientsId = xmlNewNode("RECIPIENTS", XML_ELEMENT, cmfId)

|Create FROM element and add its attributes
fromId = xmlNewNode("FROM", XML_ELEMENT, recipientsId)

retVal = xmlSetAttribute(fromId,  "NAME", "Jan Jansen" )
retVal = xmlSetAttribute(fromId,  "TYPE", "SMTP" )
retVal = xmlSetAttribute(fromId,  "ADDRESS", "jjansen@example.com" )

|Open a file for write and store the XML document
fd = seq.open("/home/ssauser/file.xml", "w" )
xmlWritePretty(fd, dtdId, 0 )
seq.close(fd)

|Free the complete XML object from memory
xmlDelete(dtdId, 0)

The resulting XML-document is shown below:

<?xml version="1.0"?>
<!DOCTYPE CMF SYSTEM "cmf1.dtd">
<CMF>
        <IDENTIFICATION
                MESSAGE-ID="34a98u0erirori"
                CLASS="order"
                SUBJECT="Subject string"
        />
        <RECIPIENTS>
                <FROM
                        NAME="Jan Jansen"
                        TYPE="SMTP"
                        ADDRESS="jjansen@example.com"
                />
        </RECIPIENTS>
</CMF>

Related topics

  • Example XML parsing


Example XML parsing

Below a piece of Baan-C code is shown for parsing and exploring the XML document which was shown in the Example XML generation.

function parse()
{
        long    fd
        long    cmfId, identId,  fromId
        long    retVal
        long    found

        string  error_string(120)
        string  messageId(20)
        string  messageClass(20)
        string  subject(100)

        |Open the XML file for reading.
        fd = seq.open ("/home/ssauser/file.xml", "r" )

        |Parse the XML file
        cmfId = xmlRead(fd, error_string)
        seq.close(fd)

        |Search for the IDENTIFICATION element
        identId = xmlFindFirst( "IDENTIFICATION", cmfId)
        if (identId <> 0 )
        then
                |Get the identificiation attributes
                retVal =  xmlGetAttribute(identId,  "MESSAGE-ID" ,messageId)
                retVal =  xmlGetAttribute(identId,  "CLASS", messageClass)
                retVal =  xmlGetAttribute(identId,  "SUBJECT", subject)
        endif

        |Search for the first FROM element
        fromId = xmlFindFirst( "FROM", cmfId)
        if (fromId <> 0)
        then
                |TODO: Get the from attributes

        endif

        |Alternative 1 to get to the FROM element
        fromId = xmlFindFirstMatch( "<CMF>.<RECIPIENTS>.<FROM>", cmfId)

        |Alternative 2 to get to the FROM element
        fromId = xmlFindFirstMatch( "?<FROM>", cmfId)

        |Alternative 3 to get to the FROM element
        fromId = xmlFindFirstMatch( "-<FROM>", cmfId)

        |Alternative 4 to get to the FROM element
        fromId = xmlFindFirstMatch( "<CMF>.<IDENTIFICATION>.right.fChild", cmfId)

        |Alternative 5 to get to the FROM element
        fromId = xmlFindFirstMatch( "parent.lChild.fChild", identId )

        |Alternative 6 to get to the FROM element
        fromId = xmlFindFirstMatch( "?<FROM NAME TYPE ADDRESS>", cmfId)

        |Alternative 7 to get to the FROM element
        fromId = xmlFindFirstMatch( "?<NAME= TYPE ADDRESS>", cmfId)

        |Alternative 8 to get to the FROM element
        fromId = xmlFindFirstMatch( "?<=""SMTP"">", cmfId)

        |Alternative 9 to get to the FROM element
        fromId = xmlFindFirstMatch( "?<TYPE=""SMTP"">", cmfId)

        |Alternative to get to the CMF element from the FROM element
        cmfId = xmlFindFirstMatch( "^<CMF>", fromId )
}

Related topics

  • Example XML generation


Verify the used characters

Synopsis

long	xmlContainsValidCharactersOnly(string inputstring)

XML library function

int	xmlContainsValidTssCharactersOnly(const char * aTss);

Description

This function verifies whether the supplied string contains valid characters only.

According to [XMLSTD], the following Unicode characters are allowed in an XML document:

    Char ::=  #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
All other characters are forbidden. There is no possibility to escape them. The forbidden characters are:
  • ASCII control characters in the range [#x0-#x1F], except the allowed characters #x9 (Horizontal Tab), #xA (Line Feed), and #xD (Carriage Return);
  • Unicode surrogate characters in the range [#xD800-#xDFFF];
  • The <not a character> Unicode values #xFFFE and #xFFFF.

Arguments

inputstring

inputstring is converted from TSS to UTF-8, and the resulting characters are checked for validity.

Return values

1 | Success; inputstring contains valid characters only.
0 | Error; conversion of inputstring from TSS to UTF-8 failed or a forbidden character was encountered in the resulting UTF-8 string.

Related topics


Serialize XML Object

Synopsis

long	xmlWrite(long fp, long fromNode, [long toNode])
long	xmlWritePretty(long fp, long fromNode, [long toNode] )
long	xmlWriteToString(ref string buffer, long fromNode, [long toNode] )
long	xmlWritePrettyToString(ref string buffer, long fromNode, [long toNode] )
string	xmlString$(long fromNode, [long toNode] )
string	xmlPrettyString$(long fromNode, [long toNode] )
long	xmlAllocString(ref string basedString(), long fromNode, [long toNode] )
long	xmlAllocPrettyString(ref string basedString(), long fromNode, [long toNode] )

XML library function

int	xmlWrite(STREAM *fp, XmlNodePointer _pTo, XmlNodePointer _pFrom, int prettyPrint);
int	xmlWriteBuffer(char *buffer, unsigned long bufferSize, XmlNodePointer pFrom, XmlNodePointer pTo, int prettyPrint);
int	xmlWriteBufferExt(char *buffer, unsigned long bufferSize, XmlNodePointer pFrom, XmlNodePointer pTo, int prettyPrint);

Description

Serialize an XML object to XML and write resulting XML document to an open stream or to an in-memory string. Any string information in the XML document is converted to UTF-8 format.

When one of the 'pretty' variants of the functions is used (i.e. xmlWritePretty(), xmlWritePrettyToString(), xmlPrettyString$(), or xmlAllocPrettyString()), then the XML data is formatted by adding new-lines and tabs to make it human readable. When one of the other functions is used, no additional formatting is done.

Arguments

fp | fp must be a file pointer opened for write obtained from a call to seq.open(), pipe.open(), ims.openfba() or ims.openvba().
fromNode, toNode | See fromNode and toNode
buffer | buffer must be a reference to a string buffer which contains the generated XML document on return of the function. The function xmlGetStringLength or xmlGetPrettyStringLength may be used to determine the required size of buffer.
basedString | basedString is a based string buffer which will implicitly be allocated to the correct size (see alloc.mem) and will be filled with the generated XML document.

Return values

xmlWrite, xmlWritePretty, xmlWriteToString, xmlWritePrettyToString:
>= 0

Success; Number of bytes written to output when successful
< 0

Error. As many bytes as possible are written to fp or buffer. If the cause of the error is not that the buffer is too small, then the exact place where the output of bytes stops, corresponds to the place in the XML tree where the first serialization error occurred. Some specific values:
-1 | Incorrect argument. For example, file pointer fp is closed, or fromNode or toNode is not a valid xml node.
-3 | Cannot write to fp (e.g. it is open for reading instead of writing), or the buffer is too small, or a TSS conversion error occured. If TSS conversion of a certain text element (e.g. an attribute name or value) fails, then the output of bytes stops before that text element.
-4 | An invalid character was encountered. The output of bytes stops just before that character. See xmlContainsValidCharactersOnly.

xmlString$, xmlPrettyString$:

A temporary string with the generated XML document. If there is not enough temporary memory available for the result, or if the serialization fails, then an empty string is returned.

xmlAllocString, xmlAllocPrettyString:
0 | Success. Even if the serialization fails, this value is returned. In that case basedString will be an empty string.
-1 | Error: the supplied basedString argument is not a based string.

Related topics


Get length of a serialized XML Object

Synopsis

long	xmlGetStringLength(long fromNode, [long toNode] )
long	xmlGetPrettyStringLength(long fromNode, [long toNode] )

XML library function

int	xmlWriteBufferExt(char *buffer, unsigned long bufferSize, XmlNodePointer pFrom, XmlNodePointer pTo, int prettyPrint);

Description

Get the length of the serialized form of an XML Object. When xmGetPrettyStringLength() is used, then the additional new-lines and tabs for human-readable formatting are taken into account.

These functions may be used to determine the required size of the buffer argument supplied to xmlWriteToString() or xmlWritePrettyToString().

Arguments

fromNode, toNode

See fromNode and toNode

Return values

>= 0

Success; Length of the generated XML document.
< 0

Error. Some specific values:
-1 | Incorrect argument. FromNode or toNode is not a valid xml node.
-3 | A TSS conversion error occured.
-4 | An invalid character was encountered. See xmlContainsValidCharactersOnly.

Related topics


De-serialize XML Object

Synopsis

long	xmlRead(long fp, ref string error, [ long whitespacehandling ] )
long	xmlReadFromString(string xmlString, ref string error, [ long whitespacehandling ] )

XML library function

XmlNodePointer	xmlRead(STREAM *fp, char *parserError, XmlContextPointer pContext);
XmlNodePointer	xmlReadExt(STREAM *fp, char *parserError, XmlWhiteSpaceHandling	whiteSpaceHandling, XmlContextPointer pContext);
XmlNodePointer	xmlReadBuffer(char *buffer, unsigned long bufferSize, char *parserError, XmlContextPointer pContext);
XmlNodePointer	xmlReadBufferExt(char *buffer, unsigned long bufferSize,char * parserError, XmlWhiteSpaceHandling whiteSpaceHandling, XmlContextPointer pContext);

Description

De-serialize an XML object by parsing an XML document and creating an in-memory object tree.

Arguments

fp

fp must be a file pointer opened for read obtained from a call to seq.open(), pipe.open(), ims.openfba() or ims.openvba().
xmlString

xmlString must be a string buffer which contains an XML document.
error

error contains a description of the error in case a parsing error occurs. This is an English text, which can be used for logging purposes. Maximum length of this error string is 120 characters.

whitespacehandling

whitespacehandling can have one of the three values XmlWhiteSpaceLegacyMode, XmlPreserveWhiteSpace, and XmlReplaceWhiteSpaceBySingleSpace. When this optional argument is not supplied, the value XmlWhiteSpaceLegacyMode is assumed. The meaning of the allowed values is as follows.
XmlWhiteSpaceLegacyMode | XmlWhiteSpaceLegacyMode means that white space is handled the same way as it was done in older versions of these functions, which did not have the whitespacehandling argument. This means (1) that each newline character in the input starts a new data node, (2) that leading white space in a data node is removed, and (3) that empty data nodes are removed.
XmlPreserveWhiteSpace | XmlPreserveWhiteSpace means that all white space in the XML document is preserved. However, it should be noted that any carriage-return line-feed character pair and any carriage-return character that is not followed by a line-feed character is translated to a single line-feed character. See also [XMLSTD], section 2.11.
XmlReplaceWhiteSpaceBySingleSpace | XmlReplaceWhiteSpaceBySingleSpace means (1) that leading and trailing white space in a data node is removed, (2) that empty data nodes are removed, and (3) that internal white space in a data node is replaced by one single space character.
It is possible to switch between the two modes XmlPreserveWhiteSpace and XmlReplaceWhiteSpaceBySingleSpace by means of the xml:space attribute. The value "preserve" switches the mode to XmlPreserveWhiteSpace. The value "default" (or any other value than "preserve") switches the mode to XmlReplaceWhiteSpaceBySingleSpace. The value of the xml:space attribute is considered to apply to all elements within the content of the element where it is specified, unless overriden with another instance of the xml:space attribute. See also [XMLSTD], Section 2.10.
In XmlWhiteSpaceLegacyMode, the xml:space attribute is ignored.

Return values

 | Success; A reference to the first in-memory node when successful.
0 | Error.

Related topics


Create a new Node

Synopsis

long	xmlNewNode(string name, [long type, long parentNode ])

XML library function

XmlNodePointer	xmlNewNode(char *name, XmlNodePointer _pParent, XmlContextPointer pContext, int nodeType);

Description

Create a new XML node.

Arguments

name | name contains the name of this node (in case type is XML_ELEMENT or XML_DTD) or the data for this node (in case type is XML_DATA or XML_PI).
type | type must be one of: XML_ELEMENT, XML_DTD, XML_DATA or XML_PI. The default value is XML_ELEMENT.
parentNode | parentNode when specified this refers to the parent node. The new node is appended to the list of child nodes. When omitted, the new node is not added to any parent node.

Return values

 | Success; A reference to the new node when successful.
0 | Error.

Related topics


Create an Element Node with Data Node

Synopsis

long	xmlNewDataElement(string name, string data, [ long parentNode ])

XML library function

XmlNodePointer	xmlNewDataElement(char *name, char *data, XmlNodePointer _pParent, XmlContextPointer pContext);

Description

Create a new XML_ELEMENT node and new XML_DATA node. The XML_DATA node is the first child of the XML_ELEMENT node.

Arguments

name | name contains the name of the XML_ELEMENT node.
data | data contains the data for the XML_DATA node.
parentNode | parentNode when specified this refers to the parent node of the new XML_ELEMENT node. This node is appended to the list of child nodes. When omitted, the new XML_ELEMENT node is not added to any parent node.

Return values

 | Success; A reference to the new XML_ELEMENT node when successful.
0 | Error.

Related topics


Rewrite Data Element

Synopsis

long	xmlRewriteDataElement(long node, string name, string data)

XML library function

int	xmlRewriteDataElement(XmlNodePointer _pNode, char *name, char *data, XmlContextPointer pContext);

Description

Find first child XML_ELEMENT node that has a name equal to name. If a matching node is found and this node does not have any child node, a new XML_DATA node with value data is added as a child node.

If a matching node is found and this node already has one or more child nodes, these child nodes are all replaced by a single new XML_DATA child node with value data.

When no matching node is found, a new child XML_ELEMENT node is appended to the list of child nodes. To this new child node a new XML_DATA node with value data is added.

Arguments

node | node is the parent node for which a matching XML_ELEMENT child node is searched.
name | name contains the name of the XML_ELEMENT node to be found.
data | data contains the data for the new XML_DATA node.

Return values

 | Success; Value of parameter node when successful.
0 | Error.

Related topics


Get data of all Elements

Synopsis

long	xmlGetDataElement(long node, string name, ref string data)
string	xmlDataElement$(long node, string name, [ string default.value ] )
long	xmlAllocDataElement(ref string basedString(), long node, string name, [ string default.value ] )

XML library function

int	xmlGetDataElement(XmlNodePointer _pNode, char *name, char *data, int sizeOfData);
int	xmlGetDataElementLength(XmlNodePointer _pNode, char *name);

Description

For each child XML_ELEMENT node that has a name equal to name, get the data contained in XML_DATA child nodes. The data from all matching nodes is concatenated.

Arguments

node | node is the parent node for which all matching XML_ELEMENT child nodes are searched.
name | name contains the name of the XML_ELEMENT node to be found.
default.value | default.value is the value that will be returned by xmlDataElement$ or will be stored in basedString when the node is invalid. When default.value is not specified, an empty string is used.
data | data contains the concatenated data for all found nodes on return. The function xmlGetDataElementLength may be used to determine the required size of data.
basedString | basedString is a based string buffer (either or not multibyte) which will implicitly be allocated to the correct size (see alloc.mem) and will be filled with the concatenated data for all found nodes.

Return values

xmlGetDataElement:
 | Success; Value of parameter node when successful.
0 | Error.
xmlDataElement$:

A temporary multibyte string with the concatenated data for all found notes.
xmlAllocDataElement:
0 | Success.
-1 | Error: the supplied basedString argument is not a based string.

Related topics


Get data length of all Elements

Synopsis

long	xmlGetDataElementLength(long node, string name)

XML library function

int	xmlGetDataElementLength(XmlNodePointer _pNode, char *name);

Description

Get the data length of a node. For each child XML_ELEMENT node that has a name equal to name, the length of the data contained in XML_DATA child nodes is counted.

This function may be used to determine the required size of the data argument supplied to xmlGetDataElement().

Arguments

node | node is the parent node for which all matching XML_ELEMENT child nodes are searched.
name | name contains the name of the XML_ELEMENT node to be found.

Return values

>=0 | Success; Length of the concatenated data for all found nodes.
-1 | Error, the specified node is incorrect.

Related topics


Set name of a Node

Synopsis

long	xmlSetName(long node, string name)

XML library function

int	xmlSetName(XmlNodePointer _pNode, char *name, XmlContextPointer pContext);

Description

Set the name of an XML_ELEMENT or XML_DTD node.

Arguments

node | node is the node for which the name is set.
name | name contains the new name.

Return values

 | Success; Value of parameter node when successful.
0 | Error.

Related topics


Set data of a Node

Synopsis

long	xmlSetData(long node, string data)

XML library function

int	xmlSetData(XmlNodePointer _pNode, char *data, XmlContextPointer pContext);

Description

Set the data of an XML_DATA or XML_PI node.

Arguments

node | node is the node for which the data is set.
data | data contains the new data value.

Return values

 | Success; Value of parameter node when successful.
0 | Error.

Related topics


Set attribute

Synopsis

long	xmlSetAttribute(long node, string attributeName, string data)

XML library function

int	xmlSetAttribute(XmlNodePointer _pNode, char *name, char *data, XmlContextPointer pContext);

Description

Set an attribute of an XML_ELEMENT or XML_DTD node.

Arguments

node | node is the node for which the attribute is set.
attributeName | attributeName is the name of the attribute. When this attribute does already exist for this node, it gets a new value, else a new attribute is added to this node. This guarantees that attribute names are always unique for a given node.
data | data contains the new attribute value.

Return values

 | Success; Value of parameter node when successful
0 | Error.

Related topics


Delete attribute

Synopsis

long	xmlDeleteAttribute(long node, string attribute )

XML library function

int	xmlDeleteAttribute(XmlNodePointer _pNode, char *name, XmlContextPointer pContext);

Description

Delete an attribute of an XML_ELEMENT or XML_DTD node.

Arguments

node | node is the node for which the attribute is deleted.
attribute | attribute is the name of the attribute to be deleted.

Return values

 | Success; Value of parameter node when successful.
0 | Error.

Related topics


Get child of a Node

Synopsis

long	xmlGetFirstChild(long node)
long	xmlGetLastChild(long node)

XML library function

XmlNodePointer	xmlGetFChild(XmlNodePointer _pNode);
XmlNodePointer	xmlGetLChild(XmlNodePointer _pNode);

Description

Get the first (most left) or last (most right) child node of an XML_ELEMENT or XML_DTD node.

Arguments

node

node is the node for which the first/last child is obtained.

Return values

 | Success; Reference to the found child node when successful.
0 | Error.

Related topics


Get parent of a Node

Synopsis

long	xmlGetParent(long node)

XML library function

XmlNodePointer	xmlGetParent(XmlNodePointer _pNode);

Description

Get the parent of a node.

Arguments

node

node is the node for which the parent is obtained.

Return values

 | Success; Reference to the parent node when successful.
0 | Error.

Related topics


Get number of child Nodes

Synopsis

long	xmlGetNumChilds(long node)

XML library function

int	xmlGetNumChilds(XmlNodePointer _pNode);

Description

Get the number of child nodes of an XML_ELEMENT or XML_DTD node.

Arguments

node

node is the node for which the number of child nodes is obtained.

Return values

 | Success; The number of child nodes.
0 | Error.

Related topics


Get sibling of a Node

Synopsis

long	xmlGetRightSibling(long node)
long	xmlGetLeftSibling(long node)

XML library function

XmlNodePointer	xmlGetRSib(XmlNodePointer _pNode);
XmlNodePointer	xmlGetLSib(XmlNodePointer _pNode);

Description

Get the right or left sibling node of a node.

Arguments

node

node is the node for which the sibling node is obtained.

Related topics


Get name of a Node

Synopsis

long	xmlGetName(long node, ref string name)
string	xmlName$(long node, [ string default.value ] )
long	xmlAllocName(ref string basedString(), long node, [ string default.value ] )

XML library function

int	xmlGetName(XmlNodePointer _pNode, char *name, int sizeOfName);
char	*xmlGetNameValue(XmlNodePointer _pNode);

Description

Get the name of an XML_ELEMENT or XML_DTD node.

Arguments

node | node is the node for which the name is obtained.
default.value | default.value is the value that will be returned by xmlName$ or will be stored in basedString when the node is invalid. When default.value is not specified, an empty string is used.
name | name is a string buffer which contains the node name on return. The function xmlGetNameLength may be used to determine the required size of name.
basedString | basedString is a based string buffer (either or not multibyte) which will implicitly be allocated to the correct size (see alloc.mem) and will be filled with the node name.

Return values

xmlGetName:
 | Success; Value of parameter node when successful.
0 | Error.
xmlName$:

A temporary multibyte string with the name of the specified node.
xmlAllocName:
0 | Success.
-1 | Error: the supplied basedString argument is not a based string.

Related topics


Get name length of a node

Synopsis

long	xmlGetNameLength(long node)

XML library function

char	*xmlGetNameValue(XmlNodePointer _pNode);

Description

Get the length of a node name.

This function may be used to determine the required size of the name argument supplied to xmlGetName().

Arguments

node

node is the node for which the length of its name is obtained.

Return values

>=0 | Success; Length of the node name
-1 | Error.

Related topics


Get number of sibling Nodes

Synopsis

long	xmlGetNumSiblings(long node)
long	xmlGetNumRightSiblings(long node)
long	xmlGetNumLeftSiblings(long node)

XML library function

int	xmlGetNumSib(XmlNodePointer _pNode);
int	xmlGetNumRSib(XmlNodePointer _pNode);
int	xmlGetNumLSib(XmlNodePointer _pNode);

Description

Get the total number of sibling nodes, the number of right or left sibling nodes.

Arguments

node

node is the node for which the number of siblings is returned.

Return values

 | Success; Number of sibling nodes found..
0 | When an error occurred or when node does not have any of the requested siblings.

Related topics


Get data of a Node

Synopsis

long	xmlGetData(long node, ref string data)
string	xmlData$(long node, [ string default.value ] )
long	xmlAllocData(ref string basedString(), long node, [ string default.value ] )

XML library function

int	xmlGetData(XmlNodePointer _pNode, char *data, int sizeOfData);
int	xmlGetDataLength(XmlNodePointer _pNode);

Description

Get the data of a node. When node is of type XML_DATA or XML_PI, only the data from this node is obtained. When node is of type XML_ELEMENT or XML_DTD, the data from all child XML_DATA and XML_PI nodes is concatenated.

Arguments

node | node is the node for which the data is obtained.
default.value | default.value is the value that will be returned by xmlData$ or will be stored in basedString when the node is invalid. When default.value is not specified, an empty string is used.
data | data is a string buffer which contains the data on return. The function xmlGetDataLength may be used to determine the required size of name.
basedString | basedString is a based string buffer (either or not multibyte) which will implicitly be allocated to the correct size (see alloc.mem) and will be filled with the data.

Return values

xmlGetData:
 | Success; Value of parameter node when successful.
0 | Error.
xmlData$:

A temporary multibyte string with the data of the specified node.
xmlAllocData:
0 | Success.
-1 | Error: the supplied basedString argument is not a based string.

Related topics


Get data length of a Node

Synopsis

long	xmlGetDataLength(long node)

XML library function

int	xmlGetDataLength(XmlNodePointer _pNode);

Description

Get the data length of a node. When node is of type XML_DATA or XML_PI, only the length of the data from this node is obtained. When node is of type XML_ELEMENT or XML_DTD, the length of the data from all child XML_DATA and XML_PI nodes is counted.

This function may be used to determine the required size of the data argument supplied to xmlGetData().

Arguments

node

node is the node for which the data length is obtained.

Return values

>=0 | Success; Length of the data in the node.
-1 | Error, the specified node is incorrect.

Related topics


Get attribute value

Synopsis

long	xmlGetAttribute(long node, string attributeName, ref string data)
string	xmlAttribute$(long node, string attributeName, [ string default.value ] )
long	xmlAllocAttribute(ref string basedString(), long node, string attributeName, [ string default.value ] )

XML library function

int	xmlGetAttribute(XmlNodePointer _pNode, char *name, char *data, int sizeOfData);
char	*xmlGetAttributeValue(XmlNodePointer _pNode, char *name);

Description

Get an attribute of an XML_ELEMENT or XML_DTD node.

Arguments

node | node is the node for which the attribute is obtained.
attributeName | attributeName is the name of the attribute.
default.value | default.value is the value that will be returned by xmlAttribute$ or will be stored in basedString when the node is invalid or does not have an attribute with the specified name. When default.value is not specified, an empty string is used.
data | data is a string buffer which contains the attribute value on return. The function xmlGetAttributeLength may be used to determine the required size of data.
basedString | basedString is a based string buffer (either or not multibyte) which will implicitly be allocated to the correct size (see alloc.mem) and will be filled with the attribute value.

Return values

xmlGetAttribute:
 | Success; Value of parameter node when successful.
0 | Error or the indicated attribute does not exist.
xmlAttribute$:

A temporary multibyte string with the value of the specified attribute.
xmlAllocAttribute:
0 | Success.
-1 | Error: the supplied basedString argument is not a based string.

Related topics


Get attribute length

Synopsis

long	xmlGetAttributeLength(long node, string attributeName)

XML library function

char	*xmlGetAttributeValue(XmlNodePointer _pNode, char *name);

Description

Get the length of an attribute.

This function may be used to determine the required size of the data argument supplied to xmlGetAttribute().

Arguments

node | node is the node for which the length of an attribute is obtained.
attributeName | attributeName is the name of the attribute.

Return values

>=0 | Success; Length of the attribute.
-1 | Error, or the indicated attribute does not exist.

Related topics


Get attribute name

Synopsis

long	xmlGetAttributeName(long node, long attributeNr, ref string attributeName)
string	xmlAttributeName$(long node, long attributeNr, [ string default.value ] )
long	xmlAllocAttributeName(ref string basedString(), long node, long attributeNr,[ string default.value ] )

XML library function

int	xmlGetAttributeName(XmlNodePointer _pNode, int index, char *name, int sizeOfName);
char	*xmlGetAttributeNameValue(XmlNodePointer _pNode, int index);

Description

Get an attribute name of an XML_ELEMENT or XML_DTD node by specifying its position.

Arguments

node | node is the node for which the attribute name is obtained.
attributeNr | attributeNr is the 1 based index in the list of attributes for this node.
default.value | default.value is the value that will be returned by xmlAttributeName$ or will be stored in basedString when the node or the attributeNr is invalid. When default.value is not specified, an empty string is used.
attributeName | attributeName is a string buffer which contains the attribute name on return. The function xmlGetAttributeNameLength may be used to determine the required size of attributeName.
basedString | basedString is a based string buffer (either or not multibyte) which will implicitly be allocated to the correct size (see alloc.mem) and will be filled with the attribute name.

Return values

xmlGetAttributeName:
 | Success; Value of parameter node when successful.
0 | Error or the indicated attribute does not exist.
xmlAttributeName$:

A temporary multibyte string with the name of the specified attribute.
xmlAllocAttributeName:
0 | Success.
-1 | Error: the supplied basedString argument is not a based string.

Related topics


Get attribute name length

Synopsis

long	xmlGetAttributeNameLength(long node, int attributeNr)

XML library function

char	*xmlGetAttributeNameValue(XmlNodePointer _pNode, int index);

Description

Get the length of an attribute name.

This function may be used to determine the required size of the argumentName argument supplied to xmlGetAttributeName().

Arguments

node | node is the node for which the length of an attribute name is obtained.
attributeNr | attributeNr is the 1 based index in the list of attributes for this node.

Return values

>=0 | Success; Length of the attribute name
-1 | Error, or the indicated attribute does not exist.

Related topics


Get number of attributes

Synopsis

long	xmlGetNumAttributes(long node)

XML library function

int	xmlGetNumAttributes(XmlNodePointer _pNode);

Description

Get the number of attributes of an XML_ELEMENT or XML_DTD node.

Arguments

node

node is the node for which the number of attributes is returned.

Return values

 | Success; Number of attributes for this node.
0 | Error or no attributes are present for this node.

Related topics


Get Node type

Synopsis

long	xmlGetType(long node)

XML library function

int	xmlGetType(XmlNodePointer _pNode);

Description

Get the type of a node.

Arguments

node

node is the node for which the type is obtained.

Return values

 | Success; Node type being one of XML_ELEMENT, XML_DTD, XML_DATA or XML_PI.
-1 | Error.

Related topics


Delete Nodes

Synopsis

long	xmlDelete(long fromNode, [ long toNode ])

XML library function

int	xmlDeleteList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlContextPointer pContext);

Description

Delete a tree or a list of trees. When this tree is a sub-tree of a larger tree, it is unlinked from this larger tree.

Arguments

fromNode, toNode

See fromNode and toNode

Return values

0 | Success; Value of parameter node when successful.
<0 | When an error occurred.

Related topics


Unlink Nodes

Synopsis

long	xmlUnlink(long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlMoveList(XmlNodePointer _pFrom, XmlNodePointer _pTo);

Description

Unlink a tree or a list of trees.

Arguments

fromNode, toNode

See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been unlinked.
0 | Error.

Related topics


Unlink and Insert Nodes

Synopsis

long	xmlInsert(long destinationNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlMoveListAndInsert(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);

Description

Unlink a tree or a list of trees and insert this list in a new list before the node referred to by destinationNode.

Arguments

destinationNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees which has been moved.
0 | Error.

Related topics


Unlink and Add Nodes

Synopsis

long	xmlAdd(long destinationNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlMoveListAndAdd(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);

Description

Unlink a tree or a list of trees and add this list to a new list after the node referred to by destinationNode.

Arguments

destinationNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been moved. .
0 | Error.

Related topics


Unlink and Append Nodes

Synopsis

long	xmlAppend(long destinationNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlMoveListAndAppend(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);

Description

Unlink a tree or a list of trees and append this list to the end of the list referred to by destinationNode.

Arguments

destinationNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been moved..
0 | Error.

Related topics


Unlink and Insert Nodes in Children

Synopsis

long	xmlInsertInChilds(long parentNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlMoveListAndInsertInChildList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);

Description

Unlink a tree or a list of trees and insert this list as the first child of the node referred to by parentNode.

Arguments

parentNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been moved.
0 | Error.

Related topics


Unlink and Append Nodes to Children

Synopsis

long	xmlAppendToChilds(long parentNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlMoveListAndAppendToChildList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest);

Description

Unlink a tree or a list of trees and append this list as the last child of the node referred to by parentNode.

Arguments

parentNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been moved. .
0 | Error.

Related topics


Duplicate Nodes

Synopsis

long	xmlDuplicate(long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlDupList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlContextPointer pContext);

Description

Duplicate a tree or a list of trees.

Arguments

fromNode, toNode

See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been created.
0 | Error.

Related topics


Duplicate Nodes to Process

Synopsis

long	xmlDuplicateToProcess(long processId, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlDupList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlContextPointer pContext);

Description

Duplicate a tree or a list of trees into another 3GL-process space.

Arguments

parentNode | processId must be a valid 3GL process identifier. This process becomes the owner of the newly created tree or list of trees.
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been created.
0 | Error.

Related topics


Duplicate and Insert Nodes

Synopsis

long	xmlDuplicateAndInsert(long destinationNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlDupListAndInsert(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);

Description

Duplicate a tree or a list of trees and insert this list in an existing list before the node referred to by destinationNode.

Arguments

destinationNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been created.
0 | Error.

Related topics


Duplicate and Add Nodes

Synopsis

long	xmlDuplicateAndAdd(long destinationNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlDupListAndAdd(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);

Description

Duplicate a tree or a list of trees and add this list to an existing list after the node referred to by destinationNode.

Arguments

destinationNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been created.
0 | Error.

Related topics


Duplicate and Append Nodes

Synopsis

long	xmlDuplicateAndAppend(long destinationNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlDupListAndAppend(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);

Description

Duplicate a tree or a list of trees and append this list to the end of the list referred to by destinationNode.

Arguments

destinationNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been created.
0 | Error.

Related topics


Duplicate and Insert Nodes in Children

Synopsis

long	xmlDuplicateAndInsertInChilds(long parentNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlDupListAndInsertInChildList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);

Description

Duplicate a tree or a list of trees and insert this list as the first child of the node referred to by parentNode.

Arguments

parentNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been created.
0 | Error.

Related topics


Duplicate and Append Nodes to Children

Synopsis

long	xmlDuplicateAndAppendToChilds(long parentNode, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlDupListAndAppendToChildList(XmlNodePointer _pFrom, XmlNodePointer _pTo, XmlNodePointer _pDest, XmlContextPointer pContext);

Description

Duplicate a tree or a list of trees and append this list as the last child of the node referred to by parentNode.

Arguments

parentNode |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first node in tree or list of trees, which has been created.
0 | Error.

Related topics


Find first Node

Synopsis

long	xmlFindFirst(string tagName, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlFindFirstInList(XmlNodePointer _pFrom, XmlNodePointer _pTo, char *criteria);

Description

Search in a tree or a list of trees and return the first XML_ELEMENT or XML_DTD, which name is equal to the string tagName.

Arguments

tagName |
fromNode, toNode | See fromNode and toNode

Return values

 | Success; Reference to first matching Node.
0 | Error or no match found.

Related topics


Find first Node using a Match Pattern

Synopsis

long	xmlFindFirstMatch(string pattern, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlFindFirstMatchInList(XmlNodePointer _pFrom, XmlNodePointer _pTo, char *pPattern);

Description

Search in a tree or a list of trees and return the first XML_ELEMENT or XML_DTD, which matches with the string pattern. The string pattern contains a search path relative to the starting node. The starting node is the list of nodes indicated by fromNode to toNode.

Arguments

pattern is a string which should conform to the following syntax:

Pattern        ::=   Part [ '.' Part ]*
Part           ::=   DepthSearch | BreadthSearch | ParentSearch | Tag |
                     RightSibling | LeftSibling |  FirstChild | LastChild | Parent
DepthSearch    ::=   '?' Tag
BreadthSearch  ::=   '-' Tag
ParentSearch   ::=   '^' Tag
Tag            ::=   '<' [Name] [Attribute]*  '>'
Name           ::=   Element name, see for a definition:  [XMLSTD].
Attribute      ::=   attname'='attvalue | attname | attname'=' | '='attvalue
RightSibling   ::=   "right"
LeftSibling    ::=   "left"
FirstChild     ::=   "fChild"
LastChild      ::=   "lChild"
Parent         ::=   "parent"

Attribute values should be surrounded by double quotes.

When the text inside a tag starts with a stand alone identifier (not followed by an equals sign '='), then, according to the above syntax, it is ambiguous whether it is an element name or an attribute name. In fact, it is interpreted as an element name. When an attribute name is meant, it should in this case be followed by an equals sign '='. This is not necessary for further attributes.

For an example see Example XML parsing.

See also fromNode and toNode.

Return values

 | Success; Reference to first matching Node.
0 | Error or no match found.

Related topics


Find Nodes

Synopsis

long	xmlFindNodes(long node, string criteria, long maxFound, [ref long numFound] )

XML library function

XmlNodePointer	xmlFindNodes(XmlNodePointer _pNode, char *criteria, int maxFound, int *pNumFound, XmlContextPointer pContext);

Description

Search in a tree starting at node and create a new tree containing references to all occurrences of XML_ELEMENT or XML_DTD nodes, which name matches with the string criteria. Searching stops when maxFound number of Nodes is found. When maxFound has value 0, searching stops when the complete tree has been traversed. The tree is traversed in the order as shown in Depth first Tree traversal order figure.

On return, the optional argument numFound contains the number of matching nodes which have been found.

Return values

The return value refers to a new tree, which contains the NodeId's of the nodes which match the name criteria. This new tree corresponds to an XML document as shown below:

<Enumeration TYPE="InMemory XmlNodes">
        <e0>id0</e0>
        <e1>id1</e1>
        ...
        <en>idn</en>
</Enumeration>

In this example idn is the decimal string representation of a nodeId of a node, which matches criteria.

Like any other tree of Nodes, the returned tree must be freed from memory by using xmlDelete().

 | Success; The new tree containing references to the found nodes.
0 | Error or no match is found.

Related topics


Find Nodes using a Match Pattern

Synopsis

long	xmlFindMatch(string pattern, long fromNode, [ long toNode ])

XML library function

XmlNodePointer	xmlFindMatchInList(XmlNodePointer _pFrom, XmlNodePointer _pTo, char *pPattern, XmlContextPointer pContext);

Description

Search in a tree or a list of trees and create a new tree containing references to all occurrences of XML_ELEMENT or XML_DTD nodes, which match with the pattern. The pattern contains a search path relative to the starting node. The starting node is the list of nodes indicated by fromNode to toNode.

Arguments

pattern is a string which should conform to the same syntax as specified for xmlFindFirstMatch.

See also fromNode and toNode.

Return values

The return value refers to a new tree, which contains the NodeId's of the nodes which match the pattern. This new tree corresponds to an XML document as shown below:

<Enumeration TYPE="InMemory XmlNodes">
        <e0>id0</e0>
        <e1>id1</e1>
        ...
        <en>idn</en>
</Enumeration>

In this example idn is the decimal string representation of a nodeId of a node, which matches the pattern.

Like any other tree of Nodes, the returned tree must be freed from memory by using xmlDelete().

 | Success; The new tree containing references to the found nodes.
0 | Error or no match is found.

Related topics


Find set of Sibling Nodes

Synopsis

long	xmlFindSetOfSiblingNodes(long node, string criteria, long maxFound, [ref long numFound])

XML library function

XmlNodePointer	xmlFindSetOfSiblingNodes(XmlNodePointer _pNode, char *criteria, int maxFound, int *pNumFound, XmlContextPointer pContext);

Description

Traverse the tree starting at node and return all occurrences of XML_ELEMENT or XML_DTD nodes which name matches with the string criteria. Searching will stop when maxFound number of Nodes have been found. When maxFound has value 0, searching will stop when the complete tree has been traversed. The tree is traversed in the breadth first order as shown in the Breadth first Tree traversal order figure.

On return, the optional argument numFound contains the number of matching nodes, which have been found.

Return values

The return value refers to a new tree, which contains the NodeId's of the nodes which match the name criteria. This new tree corresponds to an XML document as shown below:

<Enumeration TYPE="Enumeration" >
        <e0>
                <Enumeration TYPE="InMemory XmlNodeId">
                        <e0>id0</e0>
                        <e1>id1</e1>
                        ...
                        <en>idn</en>
                </Enumeration>
        </e0>
        <e1>
                <Enumeration TYPE="InMemory XmlNodeId">
                        <e0>id0</e0>
                        <e1>id1</e1>
                        ...
                        <em>idm</em>
                </Enumeration>
        </e1>
        ...
        <ek>
               ...
        </ek>
</Enumeration>

In this example idn is the decimal string representation of a nodeId of a node, which matches criteria. All matching nodes found on the same level (sibling nodes) will be grouped together in one <Enumeration TYPE="InMemory XmlNodeId"> element.

Like any other tree of Nodes, the returned tree must be freed from memory by using xmlDelete().

 | Success; The new tree containing references to the found nodes.
0 | Error or no match is found.

Related topics


Create context

Synopsis

No 3GL/4GL function

XML library function

XmlContextPointer	xmlCreateContext(long mid);

Description

Create an XML context which is bound to a 3GL/4GL process.

Arguments

mid memory

mid memory allocation id returned by mal_reserve_id().

Return values

 | Success; Pointer to an XML context.
NULL | Error.

Related topics


Delete context

Synopsis

No 3GL/4GL function

XML library function

void	xmlDeleteContext(XmlContextPointer pContext);

Description

Delete an XML context and all XML Object memory allocated on behalf of this context.

Arguments

pContext

pContext is a pointer to an XML context returned by a previous call to xmlCreateContext().

Return values

None.

Related topics


SSA ERP LN 6.1 Programmers Guide (XML object part only)

Glossary