JScript is Microsoft's version of JavaScript. The API described here relies on features of JScript that are not available in JavaScript.
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.
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.
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.
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.
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.
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.
The JScript library TaminoLib.js also includes
functionality for transaction processing. You can use the
startSession, endSession,
commit and rollback methods
of TaminoClient.