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:
To run the example, perform the following steps:
Use the Tamino Manager to create a test database. This example assumes that the database name is mydb. The collection name is Telephone.
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.
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.
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.
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):
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>
<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.
define the function ChangeCountry, which accesses the Tamino database and modifies the country of anyone who lives in Frankfurt.
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.
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.
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.
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.
creates the QueryObj instance of the
TaminoClient object.
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.
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.
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.
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.
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.
starts the processing loop, in which each document in turn is retrieved, modified and written back to the database.
uses the DOM item() method to retrieve the
current document from the document set stored in
nodeList.
uses the DOM getElementsByTagName() method
to retrieve the Country element of the current
document.
change "Germany" to "Deutschland" or vice versa.
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.
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.
tests whether any more documents were retrieved.
sets nodeList to null if no more documents
were returned. This subsequently terminates the loop processing that starts at
line 30.
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.
completes the function
ChangeCountry.
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.