Example

This section provides an example of how to use the JScript API to access and modify data in a Tamino database.

The example accesses a database that contains an extract from a fictitious telephone directory. It selects all people in the directory who live in Frankfurt, updates their country, then writes the modified data back into the database. When the HTML page that contains the JScript code is viewed in a browser, a button containing the text "Press here to start" is displayed. When you choose this button, the JScript code runs through to completion, updating all country elements as described. The JScript code does not display the updated database, so to view the changes, either you can use the Tamino Interactive Interface, or you can view the results in the browser using a combined URL and an appropriate database query in the browser's address line.

The following sections provide more detail:

Running the Example

To run the example, perform the following steps:

  1. Use the Tamino Manager to create a test database. This example assumes that the database name is mydb. The collection name is Telephone.

  2. Use the Tamino Interactive Interface to define the "Telephone" schema that the example requires. The source file that contains the schema is TelephoneSchema.tsd.

    Then use the Tamino Interactive Interface to load the test data from the file Telephone.xml into the Tamino database.

    Data for each person in the telephone directory is stored in an element named Telephone. A typical Telephone element is: 

    <Telephone>                                 
  <EntryID>127</EntryID>                    
  <LoginName>Wehner127</LoginName>          
  <PassWord>Wehner127</PassWord>            
  <Lastname>Wehner</Lastname>               
  <Firstname>Anton</Firstname>              
  <Date_of_Birth>05.01.1945</Date_of_Birth> 
  <Company_Name>KdH AG</Company_Name>       
  <Salutation>Herr</Salutation>             
  <Email>Wehner127@web.de</Email>           
  <Address>                                 
    <Street>Schulplatz 189</Street>         
    <City>Darmstadt</City>                  
    <ZIP>64287</ZIP>                        
    <Country>Germany</Country>              
    <Telephone>06150-113141387</Telephone>  
    <Fax>06150-1649896197</Fax>             
  </Address>                                
</Telephone>

    At this point, you can check to see how many people in the test database live in Frankfurt by using the Tamino Interactive Interface to submit the query Telephone[Address/City="Frankfurt"] to the database.

  3. Open the HTML file SampleChangeCountry.htm (see below) in your browser. This page contains the embedded JScript code to access and modify the telephone directory. When you view the HTML page, you will see a button with the text "Press here to start". Choose the button to activate the JScript code. After a few seconds, the code completes and a result message is displayed in the browser.

    The effect of the JScript code is to change the country of all persons living in Frankfurt. If the country is "Germany" it is changed to "Deutschland" and vice versa.

  4. Use the query Telephone[Address/City="Frankfurt"] to display the new entries for all people living in Frankfurt and check that the country elements have changed.

Implementation

The HTML page that contains the JScript source code is SampleChangeCountry.htm (the file is provided with this software package). The contents are as follows (line numbers are prepended to simplify the explanations):

SampleChangeCountry.htm

01:  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
02:  <HTML>
03:  <HEAD>
04:  <TITLE>Test Page for Tamino's JavaScript API</TITLE>
05:  <SCRIPT LANGUAGE="JavaScript" SRC="..\TaminoLib.js"></SCRIPT>
06:  <SCRIPT LANGUAGE="JavaScript">
07:  function ChangeCountry ()
08:  {
09:      var dbname="http://localhost/tamino/mydb/Telephone";
10:      var QueryObj;
11:      var QueryResult;
12:      var itemSelected;
13:      var country;
14:      var xqlResult;
15:      var countdg = 0;
16:      var countgd = 0;
17:  	var QueryVal='Telephone[Address/City="Frankfurt"]';
18:      var pageSize=12;
19:
20:  	document.write("<P>Processing query '" + QueryVal + "' in database/collection '" + dbname + "'.");
21:
22:      QueryObj = new TaminoClient(dbname,pageSize);
23:      QueryResult = QueryObj.query(QueryVal);
24:      if (QueryResult.errorNo == "0") {
25:        xqlResult=QueryResult.getResult();
26:        if (xqlResult)
27:          {
28:          var nodelist = xqlResult.childNodes;
29:          QueryObj.startSession();
30:          while (nodelist)
31:            {
32:            for (i=0;i<nodelist.length;i++)
33:            	{
34:              itemSelected = nodelist.item(i);
35:              country = itemSelected.getElementsByTagName("Country").item(0).childNodes.item(0).data;
36:              if (country == "Germany")
37:                {
38:                itemSelected.getElementsByTagName("Country").item(0).childNodes.item(0).data = "Deutschland";
39:                countgd++;
40:                };
41:              else
42:                {
43:                itemSelected.getElementsByTagName("Country").item(0).childNodes.item(0).data = "Germany";
44:                countdg++;
45:                };
46:              QueryObj.process(itemSelected);
47:              };
48:
49:            QueryResult = QueryResult.getNext();
50:            if (QueryResult)
51:              {
52:              xqlResult= QueryResult.getResult();
53:              nodelist = xqlResult.childNodes;
54:              }
55:            else
56:              {
57:              nodelist = null;
58:              };
59:            };
60:          QueryObj.commit();
61:          QueryObj.endSession();
62:
63:          document.write("<P>Processing ended.");
64:          document.write("<BR>Changed " + countdg + " times 'Germany' to 'Deutschland'.");
65:          document.write("<BR>Changed " + countgd + " times 'Deutschland' to 'Germany'.");
66:
67:          return(1);
68:          }
69:        else
70:          document.write("<P>No Data Returned");
71:        }
72:      else
73:        document.write("<P>Error = "+QueryResult.errorText);
74:  };
75:  </SCRIPT>
76:  </HEAD>
77:  <BODY>
78:  <P>Please press the button to start processing ...
79:  <form>
80:  <input type="button" name="Button1" value="Press here to start" onClick="ChangeCountry()">
81:  </form>
82:  <P>... and wait for the result to be displayed.
83:  </BODY>
84:  </HTML>

Explanatory Comments

Line 5

<SCRIPT LANGUAGE="JavaScript" SRC="../TaminoLib.js"></SCRIPT> causes the browser to read in the standard Tamino JScript library from the file TaminoLib.js. This library provides the low-level HTTP communication between the JScript client (i.e. the current HTML page) and the Tamino database. See the API Reference Section for a full description.

Lines 7-74

define the function ChangeCountry, which accesses the Tamino database and modifies the country of anyone who lives in Frankfurt.

Line 80

creates the button that is displayed with the text "Press here to start" in the browser window. The onClick event handler causes the function ChangeCountry to be activated when you choose the button.

Line 9

var dbname="http://localhost/tamino/mydb/Telephone"; specifies the HTTP address of the Tamino database mydb and the collection Sample. This example assumes that the database is on your local machine, so "localhost" can be used in the URL of the database. Be aware that if you specify the collection name in the URL you cannot specify this or another collection name in the methods supporting this (optional) parameter. You can use the property XMLDB to change the URL or collection name if necessary.

Line 17

defines the query that is used in line 23 to retrieve all Telephone elements whose city element has the value "Frankfurt", i.e. to retrieve the data for all people living in Frankfurt.

Line 18

specifies the page size, i.e. the maximum number of Telephone elements that should be returned per call to the database. The first call will retrieve entries 1 to 12, the next call will retrieve entries 13 to 24 and so on. The API places no upper limit on the page size you can specify, but there may be system limitations, such as the amount of memory available on your computer, which limit the page size.

Line 22

creates the QueryObj instance of the TaminoClient object.

Line 23

invokes the query method of the QueryObj object. This causes the query that is stored in the QueryVal variable to be sent as an HTTP request to the URL of the Tamino database. The result document is stored in the QueryResult object. The number of documents that match the query is limited to the value specified in the pageSize variable. In this example, pageSize was set to 12, so if there are more than 12 documents that match the query, only the first 12 will be returned. To return the remaining documents that match the query, the loop mechanism at line 30 is used.

Line 25

invokes the getResult method of the QueryObj object. This causes the xql:result element of the returned result structure to be delivered and stored in the variable xqlResult.

Line 28

extracts the child nodes of the xql:result element from the result document and stores them in the variable nodeList. The variable nodeList now contains a set of documents that matched the query. The childNodes() DOM method returns a DOM nodeList, so DOM methods can be applied to nodeList.

Line 29

opens a session in Tamino. The session key and session ID that are returned by Tamino are handled transparently by the API. Using this method enables Tamino to keep the user context and make transaction control (methods commit and rollback) possible. In line 60 the updates are committed by the commit method of the QueryObj object, and in line 61 the session is closed.

Line 30

starts a processing loop which continues as long as there are elements to be processed. During each pass of the loop, the number of documents specified by the variable pageSize is processed.

Line 32

starts the processing loop, in which each document in turn is retrieved, modified and written back to the database.

Line 34

uses the DOM item() method to retrieve the current document from the document set stored in nodeList.

Line 35

uses the DOM getElementsByTagName() method to retrieve the Country element of the current document.

Lines 36-45

change "Germany" to "Deutschland" or vice versa.

Line 46

sends the modified document back to Tamino as an HTTP request that includes the data of the current document and specifies the X-Machine _process request. This tells Tamino to write the document to the database.

Line 49

retrieves the next set of documents that match the query by using the getNext() method. As before, the number of documents that are retrieved cannot exceed the value specified in the variable pageSize.

Line 50

tests whether any more documents were retrieved.

Line 57

sets nodeList to null if no more documents were returned. This subsequently terminates the loop processing that starts at line 30.

Line 67

sets a return value of 1 for the function ChangeCountry. This is not strictly required, but it would allow a JScript statement of the type if (ChangeCountry) {...} elsewhere in the HTML page to test whether ChangeCountry completed successfully and to take appropriate action.

Line 74

completes the function ChangeCountry.

Lines 77-83

cause a button with the text "Press here to start" to appear when the HTML page is displayed in a browser. The onClick attribute causes the function ChangeCountry to be started when the user chooses the button in the browser window.