Using the API

JScript is Microsoft's version of JavaScript. The API described here relies on features of JScript that are not available in JavaScript.

What is Provided

The API provides a DOM (Document Object Model) oriented interface to Tamino for Windows systems running Microsoft's Internet Explorer version 5.x or 6.x (IE). The script library can be used in the IE browser, or in any server-side environment that supports active scripting such as Active Server Pages (ASP) or Software AG's System Management Hub. This section gives an overview of the main objects and their methods that are provided in the API, and it indicates the basic programming techniques that you can use to access and modify a Tamino database. For a full definition of the objects and methods provided by the API, see the section API Reference Section.

TaminoLib.js Library

The functionality of this API, including HTTP communication with the Tamino X-Machine, is provided in the TaminoLib.js library. This library contains objects and methods for retrieving and modifying data in a Tamino database. The library is located in the directory <TaminoInstallDir>\SDK\JScriptAPI.

Instantiating TaminoClient

One of the first steps in your JScript code is generally to create a TaminoClient object. The definition of this object is provided in the TaminoLib.js library. One of the arguments that you specify when you create the object defines the database and collection that is to be accessed whenever any of the object's methods is invoked. The methods provided by this object perform all of the basic communication operations with Tamino, such as submitting an XML database query or creating, updating or deleting data.

To create a TaminoClient object that can be used to communication with a given Tamino database, use statements of the form: 

var dbname="http://localhost/tamino/mydb/mycollection";
var QueryObj;
QueryObj = new TaminoClient(dbname, ...);

where mydb and mycollection are the names of the database and collection that you wish to access.

Performing a Query

You can use the query method of the newly-created object to submit a query to the database, using statements of the form: 

var QueryResult;
var QueryVal="xqlquery";
QueryResult = QueryObj.query(QueryVal);

where "xqlquery" is a database query such as Telephone[Address/City="Frankfurt"]. The result of this operation is an object (named "QueryResult" in this example) that contains the data that Tamino returns for the query. You can use the getResult method of the QueryResult object to access the query result element: 

var xqlResult=QueryResult.getResult();

This creates an object that contains the xql:result part of the data that Tamino returns.

To get a nodelist, you can now use the DOM method childNodes of the xqlResult object: 

var nodelist=xqlResult.childNodes

If many documents in the Tamino database match the query, Tamino restricts the number of matching documents to the page size that you specified when you created the TaminoClient object. The default page size is 5. A value of 0 means 'no limitation'.

To access any given document in the result list, use statements of the form: 

var itemSelected;
itemSelected = nodeList.item(n);

where n is the index of the document that you want to access (the indexing starts at 0, not 1).

You can apply various DOM methods to the document thus retrieved. For example, to access the elements of the document, use the DOM method getElementsByTagName in statements of the form: 

var zip;
zip = itemSelected.getElementsByTagName("elementname").item(0).childNodes.item(0).data;

where elementname is the name of the element.

Microsoft's Internet Explorer contains an implementation of the DOM for JScript, so any HTML page that contains JScript code has access to the DOM interface when it is viewed in this browser.

Updates

To write a modified node back to the Tamino database, use the process method of the TaminoClient object, specifying as a parameter the name of the object that contains the modified element, for example: 

var storeResponse = QueryObj.process(itemSelected);

where QueryObj is the TaminoClient object you created previously.

The process method issues a _process request to the X-Machine, thus causing the document to be updated in the database. Since the root element of each document has a unique value for the mandatory attribute ino:id, the document to be modified is identified uniquely.

The process method builds a URL of the form http://hostname/DatabaseLocation/DatabaseName/CollectionName?_process="UpdatedDocument", where UpdatedDocument is the contents of the document, and sends this URL to Tamino. See the section Requests using X-Machine Commands for more details.

Dynamic HTML

You can use Dynamic HTML to build an interactive application that accesses the database, retrieves data, displays the data in the browser, allows you to change the data, and sends the changed data back to be stored in the Tamino database.

Transaction Processing

The JScript library TaminoLib.js also includes functionality for transaction processing. You can use the startSession, endSession, commit and rollback methods of TaminoClient.