XML, which will be used to explain the usage of dmmXML

<server>
           <received action="userMsg" sendFrom="test3">
                     <data game="27" time="12"/>
                     <data game2="22.8" time="17" isLogin="true"/>
                     <data2>
                               <test value="Client server">XML Socket server</test>
                     </data2> 
           </received>
 </server>      

List of functions

Description of functions
-----------------------------------------------------------------------------------------------------------------------------------------------------------

new
It is necessary to initiate the dmmXML XTRA before the first use.

Example - Director
global xml
openXlib the pathName&"dmmXML.x32"
xml=new(xtra "dmmXMLParser")

If the library dmmXML.x32 is located in the XTRAS folder it is enough to insert
global xml
xml=new(xtra "dmmXMLParser")

Example - Authorware
xml:=NewObject("dmmXMLParser")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=registration( name: string, code:string)
This function has to be called before the first use of the dmmXML immediately after its initialisation. Unless the right registration name and number are inserted, an announcement "this is a demo version" will appear.

Parametres
Type of name is string, for the demo version name = "dmm".
Type of code is string, for the demo version code= "demo". The chain for commercial version is unique.
To register the user will receive parameters code and name.

Very important
For safety reasons incorrect parameters can be only inserterted 3 times in the function registration. If you insert incorrect parameters name and code more times the registration is blocked and the XTRA will not work. You will be informed about it by a dialogue window. In this case you´ve got to restart Director or Authorware.

Note: Parameters name="dmm" and code="demo" are not considered as incorrect.

Example - Director
global xml
xml.registration("dmm", "demo")

Example - Authorware
CallObject(xml; "registration"; "dmm"; "demo")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

list=xtraVersion()
The function returns information about the XTRA dmmXML. The function returns values in the format Abstract Data Types:
[#fileType: "Xtra (32)",
 #CompanyName: "Studio dmm",
 #FileDescription: "XTRA dmmXML for work with XML documents",
 #FileVersion: "1.0.0.0", #InternalName: "dmmXML",
 #LegalCopyRight: "© 1992-2006 Studio dmm",
 #LegalTradeMarks: "Studio dmm",
 #OriginalFileName: "dmmXML.x32",
 #productName: "dmmXML",
 #productVersion: "1.0.0.0"]

The meaning of the items is clear and it is not necessary to describe it closer.

Parametres
There are no parametres in this function.

Example - Director
global xml
xv=xml.xtraVersion()
put "FileDescription:" && xv.FileDescription
put "FileVersion:" && xv.FileVersion


Example - Authorware
xv:=CallObject(xml; "xtraVersion")
Trace("FileDescription: " ^ xv[#FileDescription])
Trace("FileVersion: " ^ xv[#FileVersion])

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=errorMsg()
The function gives text of the error that occured while working with dmmXML. If everything went well, the function gives an empty chain.

Parametres
There are no parametres in this function.

Example - Director
global xml
xml.loadFromFile(the pathName&"data.xml")
error=xml.errorMsg()
if error="" then ....

Example - Authorware
error:=CallObject(xml; "errorMsg")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=isNoError()
The function gives back true, if no error occured during an operation. If an error occurs the function gives back false.

Parametres
There are no parametres in this function.

Example - Director
global xml
xml.loadFromFile(the pathName&"data.xml")
if xml.isNoError() then ...

Example - Authorware
error:=CallObject(xml; "isNoError")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=errorDialog(dialog: boolean)
Using this function we can set whether a dialogue window, showing error statement appears at the moment of an error or not. This setting only functions in Autor mode and it simplifies the application debugging. If you decide not to set the dialogue window you can check the errors using the function errorMsg().

Parametres
Dialog is the only parameter of the function, whose type is boolean. If the value is true, the dialogue window with error statement is opened with every error in the XTRA. For the parameter value false the window is not shown. Default setting is dialog=false.

Example - Director
global xml
xml.errorDialog(true)

Example - Authorware
CallObject(xml; "errorDialog"; true)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=errorLog(logFile: string, logSave: boolean)
Using this function we can set whether an error in the XTRA is saved to text log file at the time of the error or not. This setting only functions in Autor mode and it simplifies the application debugging.

Parametres
The function has two parametres. The parameter logFile represents name of the log file that we want to save the errors to. Type of the logSave parametre is boolean. If its value is true, every error in the XTRA is saved to log file. If its value is false nothing will be saved. Default setting is logSave=false.

Example - Director
global xml
xml.errorLog(the pathName&"log.txt", true)

Example - Authorware
CallObject(xml; errorLog; FileLocation ^ "log.txt"; true)

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=loadFromFile(xmlFile:string)
The function loads the XML document saved on hard disc. The function returns the value true in case the XML document exists and its XML format is correct. Otherwise it gives false.

Parametres
Type of XmlFile is string and we insert there name of the XML file including the path.

Example - Director
global xml
xml.loadFromFile(the pathName&"data.xml")

Example - Authorware
CallObject(xml; "loadFromFile"; FileLocation ^ "data.xml")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=loadFromText(xml:string)
The function loads the XML document saved in the parameter xml. The function returns true in case the XML format of the document is correct. Otherwise it gives false.

Parametres
Type of Xml is string and we insert there the xml document.

Example - Director
global xml
xml.loadFromText("<received action='userMsg' sendFrom='test3'>")

Example - Authorware
CallObject(xml; "loadFromText"; "<received action='userMsg' sendFrom='test3'>")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

void=startXML()
The function sets browsing of the XML document at the beginning.

Parametres
The function has no parametres.

Note: The functions loadFromFile and loadFromText call the function startXML automatically.

Example - Director
global xml
xml.startXML()

Example - Authorware
CallObject(xml; "startXML")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=getXML()
The function returns the part of the XML document that corresponds to the chosen node in the XML document.

Parametres
The function has no parametres.

Example - Director
global xml
docXml=xml.getXML()

Example - Authorware
docXml:=CallObject(xml; "getXML")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=getNodeName()
The funciton returns name of the chosen node in the XML document.

Parametres
The function has no parametres.

Example - Director
global xml
node=xml.getNodeName()

Example - Authorware
node:=CallObject(xml; "getNodeName")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=selectSingleNode(nodeName:string)
The function choses the node in the XML document, whose name in the chosen part is unique. By gradual calling the funciton selectSingleNode we go deeper in the XML document. If the node defined in the parameter exists, the function returns true. Otherwise the value flase is returned.

Parametres
Type of NodeName is string and we insert there name of the node in the XML document that we want to choose.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
put xml.getNodeName()

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
trace(CallObject(xml; "getNodeName"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=nodeCount(nodeName:string)
This function is infortmative only and it returns number of nodes that have in the given branche the name defined in the parameter.

Parametres
Type of NodeName is string and we insert there name of the node in the XML document that we want to get information about.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
number=xml.nodeCount("data")

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
number:=CallObject(xml; "nodeCount"; "data")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=selectNode(nodeName:string, item: integer)
This function is similar to the funciton selectSingleNode. The only difference is that we use it in the cases when the names of nodes are not unique. In addition, this function has the parameter item, which defines order of the node that we want to choose. If the node defined by the parametres nodeName and item exists, the function returns true. Otherwise the value flase is returned.

Parametres
Type of NodeName is string and we insert there name of the node in the XML document we want to choose. Type of Item is integer and we insert there order of the node in a group of nodes with the name defined in nodeName.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
xml.selectNode("data", 2 )
put xml.getXML()

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
CallObject(xml; "selectNode"; "data"; 2 )
trace(CallObject(xml; "getXML"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=childCount()
This function is informative only and it returns number of descendants of the actual node in the XML document.

Parametres
The function has no parametres.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
number=xml.childCount()

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
number:=CallObject(xml; "childCount")

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=selectChild( item: integer)
This function is similar to the funciton selectNode and it defines the descendant of the actual node in the XML document.If the node exists, the function returns true. Otherwise the value flase is returned.

Parametres
Type of Item is integer and it defines order of node descendant in the XML document that we want to choose.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
xml.selectChild(3)
put xml.getXML()

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
CallObject(xml; "selectChild"; 3 )
trace(CallObject(xml; "getXML"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=parentNode()
The function takes the parent node in the XML document as actual. If there is a parent node the function returns true. Otherwise the value flase is returned.

Parametres
The function has no parametres.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
xml.parentNode()
put xml.getNodeName()

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
CallObject(xml; "parentNode" )
trace(CallObject(xml; "getNodeName"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=nextNode()
The function takes the next node in the XML document as actual. If there is a next node the function returns true. Otherwise the value flase is returned.

Parametres
The function has no parametres.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
xml.selectNode("data", 2)
xml.nextNode()
put xml.getNodeName()

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
CallObject(xml; "selectNode"; "data"; 2 )
CallObject(xml; "nextNode" )
trace(CallObject(xml; "getNodeName"))
-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=pathNode(nodes:string)
This function enables to set the actual node deep in the XML document very quickly.

Parametres
Type of the parameter nodes is string and we insert there the path to the desired node in the XML document. In the parameter we insert names of nodes divided by "/".

Example - Director
global xml
xml.startXML()
xml.pathNode("received/data2/test")
put xml.getNodeName()

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "pathNode"; "received/data2/test")
trace(CallObject(xml; "getNodeName"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=getText()
The function returns string value of the chosen node.

Parametres
The function has no parametres.

Example - Director
global xml
xml.startXML()
xml.pathNode("serve/received/data2/test")
put xml.getText()

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "pathNode"; serve/received/data2/test")
trace(CallObject(xml; "getText"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

string=getTextAttr(attrName: string)
The function returns string attribute value of the chosen node.

Parametres
Type of AttrName is string and we insert there name of the atribute whose value we want to get.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
put xml.getTextAttr("sendFrom")

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
trace(CallObject(xml; "getTextAttr"; "sendFrom"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

boolean=getBoolAttr(attrName: string)
Funkce vrací hodnotu boolean atributu vybraného uzlu.

Parametres
AttrName je typu string a zadáváme zde jméno atributu, jehož hodnotu chceme získat.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
xml.selectNode("data", 2 )
put xml.getBoolAttr("isLogin")

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
xml.selectNode("data", 2 )
trace(CallObject(xml; "getBoolAttr"; "isLogin"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

integer=getIntAttr(attrName: string)
Funkce vrací hodnotu integer atributu vybraného uzlu.

Parametres
AttrName je typu string a zadáváme zde jméno atributu, jehož hodnotu chceme získat.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
xml.selectNode("data", 1 )
put xml.getIntAttr("game")

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
xml.selectNode("data", 1 )
trace(CallObject(xml; "getIntAttr"; "game"))

-----------------------------------------------------------------------------------------------------------------------------------------------------------

double=getDoubleAttr(attrName: string)
Funkce vrací hodnotu double atributu vybraného uzlu.

Parametres
AttrName je typu string a zadáváme zde jméno atributu, jehož hodnotu chceme získat.

Example - Director
global xml
xml.startXML()
xml.selectSingleNode("received")
xml.selectNode("data", 2 )
put xml.getDoubleAttr("game2")

Example - Authorware
CallObject(xml; "startXML")
CallObject(xml; "selectSingleNode"; "received")
xml.selectNode("data", 2 )
trace(CallObject(xml; "getDoubleAttr"; "game2"))