This document describes the class TaminoClient of the JScript API.

• Instantiating

• Constants

• Properties

• Methods

---

Instantiating

This constructor has a variable number of parameters. If any parameter is omitted, the corresponding default value is used. The parameters are:

• Database URL

• Page size (default is 5)

• HTTP user name

• HTTP password

Example

var tam = new
TaminoClient(); var tam = new
TaminoClient(http://mypc.mycompany.com/tamino/xml/collection); var tam = new
TaminoClient(http://mypc.mycompany.com/tamino/xml/collection,6,"myname","mypassword");

Constants

• Transactionality Constants

• Microsoft XMLDOM Node Constants

Transactionality Constants

Name	Value	Usage
XINOSESSIONID	X-INO-Sessionid	SessionID returned by Tamino
XINOSESSIONKEY	X-INO-Sessionkey	SessionKey returned by Tamino
YES	yes	Specifying "LockWaitMode"
NO	no	Specifying "LockWaitMode"
PROTECTED	protected	Specifying isolation level
UNPROTECTED	unprotected	Specifying isolation level
SHARED	shared	Specifying isolation level

Microsoft XMLDOM Node Constants

Name	Value	Usage
NODE_ELEMENT	1	when using Microsoft DOM methods
NODE_ATTRIBUTE	2
NODE_TEXT	3
NODE_CDATA_SECTION	4
NODE_ENTITY_REFERENCE	5
NODE_ENTITY	6
NODE_PROCESSING_INSTRUCTION	7
NODE_COMMENT	8
NODE_DOCUMENT	9
NODE_DOCUMENT_TYPE	10
NODE_DOCUMENT_FRAGMENT	11
NODE_NOTATION	12

Properties

• XMLDB

• user

• password

• pageSize

• xmlHeader

• xmlbase

• userAgent

• acceptLanguage

• userDefined Headers

• realCursoring

• scrollable

XMLDB

Name	XMLDB
Example	tam.XMLDB= "http://mypc.mycompany.com/tamino/xml/collection";
Description	This is the HTTP address of the database that you want to access. The default is null. You must set up the database path this way if you did not set it up in the constructor. In a browser it may be restricted to the host where the web server resides. A collection name must be included.

user

Name	user
Example	tam.user="myuserid";
Description	This is the user ID that the web server recognizes.

password

Name	password
Example	tam.password="mypassword";
Description	This is the password that the web server recognizes.

pageSize

Name	pageSize
Example	tam.pageSize=10;
Description	This sets the page size for Tamino queries. The default is 5. A value of "0" means there is no limitation, all resulting documents are returned.

xmlHeader

Name	xmlHeader
Example	tam.xmlHeader='<?xml version="1.0"?>';
Description	This controls the header that is used when XML documents are sent to Tamino during the Update, Insert and Process methods The default is '<?xml version="1.0"?>'. You will probably not have to change this.

xmlbase

Name	xmlbase
Example
Description	This sets an xml:base for query responses to override the base URL of TaminoClient or the document URI in case of getDocument. This is propagated to each TaminoResult object instantiated by the TaminoClient.

userAgent

Name	userAgent
Example	tam.userAgent="WAP1.0"
Description	This controls the value of the HTTP header User-Agent in all HTTP requests. The default value is something similar to HAS/JscriptTaminoAPILegacy_4_1_4_1/Browser IE6.

acceptLanguage

Name	acceptLanguage
Example	tam.acceptLanguage="fr"
Description	This controls the value of the HTTP header Accept-Language in all HTTP requests. The default is "en".

userDefined Headers

Name	userDefinedHeaders
Example
Description	If set to an object, this instantiates the object's properties and values to additional HTTP headers.

realCursoring

Name	realCursoring
Example	tam.realCursoring="off"
Description	This controls whether cursoring is used or not. It can take either of two values: "on" (default) or "off". If set to "on", cursoring is selected within sessions.

scrollable

Name	scrollable
Example	tam.scrollable="off"
Description	This controls whether backward scrolling within a cursor is used or not. It can take either of two values: "on" (default) or "off".

Methods

• Configuring the Tamino JScript Object

• Query Operations

• Update Operations

• Binary Operations

• Manipulating XML documents by URL

• Transactionality Support

• Metadata Support

• Diagnosis

• Special Methods requiring filter NodeLevelUpdate.dll

Configuring the Tamino JScript Object

setUserPassword

Name	setUserPassword
Example	tam.setUserPassword("myID","mypassword");
Description	This sets the user ID and password to the parameter values specified. These are only required if the Tamino web server is using security. If you leave them blank and security is applied then IE5 will prompt you to supply values. This method is a convenience which allows you to set the user ID and the password in one call.

Query Operations

xquery

Name	xquery
Result Type	TaminoResult
Example	var tamResult=tamClient.xquery("for $sq in input()/Square return $sq");
Description	This causes an XQuery to be performed. Queries deliver Tamino Result instances. If the query succeeds with one or more nodes, then they are included in the Tamino Result object in a page. The maximum size of the page is determined by the client object pageSize attribute. Pages of pageSize will ONLY be returned if a transactional session is in progress. The next and previous pages can be read using methods exposed by the Tamino Result object. The setting of the offset (10 in the example) is optional. It determines the starting offset of the returned nodes.

query

Name	query
Result Type	TaminoResult
Example	var tamResult=tam.query('Telephone[Lastname="Schmidt"]',10);
Description	This causes a X-query to be performed. In addition to User-Agent and Accept-Language Headers, the Cache Control Header is set to "no-cache". Queries deliver Tamino Result instances. If the query succeeds with one or more nodes, then they are included in the Tamino Result object in a page. The maximum size of the page is determined by the client object pageSize attribute. The next, last, previous or first pages can be read using methods exposed by the Tamino Result object. The setting of the offset (10 in the example) is optional. It determines the starting number of the returned documents.

Update Operations

process

Name	process
Result Type	TaminoResult
Example	tamResult=tam.process(myelementNode);
Description	The Tamino object attempts to store the element using HTTP/1.1 POST and the _process verb. In addition to User-Agent and Accept-Language Headers, the Content-Type Header is set to "application/x-www-form-urlencoded; charset=utf-8". If the attribute ino:id is set to a numeric value in the domain of ino IDs, the element overwrites the element with this ID if it already exists, otherwise an error occurs. If no ID is present, a unique ID is assigned. A TaminoResult object is returned. The document type and the ino:id can be extracted from the Result object.

processNodeList

Name	processNodeList
Result Type	TaminoResult
Example
Description	This processes all element nodes in a DOM nodelist.

processString

Name	processString
Result Type	TaminoResult
Example
Description	This processes an XML document as a string. Tamino checks if it is well-formed.

insert

Name	insert
Result Type	TaminoResult
Example	tamResult=tam.insert(myelementNode);
Description	This is a variation of the process method to be used when the user wishes to ensure that a new instance will be created. Any ino:id attribute in the element is reset. As a consequence, a new ID is assigned by Tamino. A TaminoResult object is returned.

update

Name	update
Result Type	TaminoResult
Example	tamResult=tam.update(myelementNode,someINOId);
Description	This is a variation of the process method to be used when the user wishes to ensure that a specific instance will be overwritten. Any ino:id attribute in the node supplied as a parameter is ignored; the ID specified in the second parameter is used instead. A TaminoResult Object is returned. This method call can be used to replace a document with a known ID with another document. If the ino:id is not assigned, an error occurs.

xqueryUpdate

Name	xqueryUpdate
Result Type	TaminoResult
Example	var tamResult = tamClient.xqueryUpdate("update replace input()/TelephoneBook/entry/nr[.='12345'] with <nr>45678</nr>");
Description	This causes an XQuery update to be performed. Updates deliver Tamino Result instances. If the update succeeds with one or more nodes then they are included in the Tamino Result object.

inodelete

Name	inodelete
Result Type	TaminoResult
Example	tamResult=inodelete(someNode);
Description	The Tamino object attempts to delete the document specified by the node parameter, using HTTP/1.1 POST and the _delete verb. The node must correspond to a document type known to the database, and an ino:id attribute must be set to an ID in the database. This is the case if the node is returned by a query. In addition to User-Agent and Accept-Language Headers, the Content-Type Header is set to "application/x-www-form-urlencoded;charset=utf-8".

querydelete

Name	querydelete
Result Type	TaminoResult
Example	tamResult=tam.querydelete[someQuery];
Description	The Tamino object attempts to delete all documents that are described by the query. In addition to User-Agent and Accept-Language Headers, the Content-Type Header is set to "application/x-www-form-urlencoded; charset=utf-8".

Binary Operations

getBinary

Name	getBinary
Result Type	TaminoResult
Example	var tamResult = tamClient.getBinary("BIN/BIN/Smiley"); var bytes = tamResult.BIN;
Description	This causes a GET of the specific binary. The document to retrieve is specified by the first. The byte array of raw data can be retrieved by inspecting the BIN property of Tamino Result.

putBinary

Name	putBinary
Result Type	TaminoResult
Example	var tamResult = tamClient.putBinary("BIN/BIN/Smiley", "image/gif", bytes);
Description	This causes a binary PUT of the specific byte array. The document type (optional) and document name is given by the first parameter. The Content-Type is specified by the second parameter. The third parameter is the byte array of raw data.

Manipulating XML documents by URL

A URL may be relative to the URL value in the XMLDB property, that is to say it may specify the document type name and identifier only; or it may be absolute, specifying the whole URL.

The identifier is either the ino ID with a prefix of "@", or a document name if it is assigned.

Examples:

• dogs/@2536

• dogs/black/labrador.xml

• http://mypc.mycompany/tamino/xml/animals/dogs/@2536

• http://mypc.mycompany/tamino/xml/animals/dogs/labrador.xml

getDocument

Name	getDocument
Type	TaminoResult
Example	tamResult=tam.getDocument("someDoctype/@9576");
Description	The Tamino object attempts to fetch the document specified by the relative URL, specifying the document type and the ino:id. An absolute URL is also accepted, using HTTP/1.1 GET. In addition to User-Agent and Accept-Language Headers, the Cache-Control Header is set to "no-cache". A Tamino result is returned. The Document element is available in via the method getResult.

putDocument

Name	putDocument
Type	TaminoResult
Example	tamResult=tam.putDocument("style/nice.xsl",documentNode);
Description	The Tamino object attempts to store the document specified by the relative URL, using HTTP/1.1 PUT. The User-Agent and Accept-Language Headers are set. A TaminoResult Object is returned. GetResult yields null. The HTTP status code can be used to determine if a document is overwritten or not. 200 implies overwritten; otherwise a new document has been created.

head

Name	head
Type	TaminoResult
Example	tamResult=tam.head("style/nice.xsl");
Description	The Tamino Client tests the status of a document with the relative URL or absolute URL, using HTTP/1.1 HEAD. The User-Agent and Accept-Language Headers are set. A Tamino Result object is returned. GetResult yields null. The HTTP status code can be used to determine if a document exists or not. In addition, the HTTP headers yield the date last updated if it exists.

deleteDocument

Name	deleteDocument
Type	TaminoResult
Example	tamResult=tam.deleteDocument("style/nice.xsl");
Description	The Tamino object attempts to delete the document specified by the relative URL or absolute URLs, using HTTP/1.1 DELETE. The User-Agent and Accept-Language Headers are set. A TaminoResult object is returned. GetResult yields null. The HTTP status code can be used to determine if a document was deleted or not.

Transactionality Support

startSession

Name	startSession
Result Type	TaminoResult
Example	tam=new TaminoClient(); tam.XMLDB="http://mypc.mycompany.com/tamino/xml/collection"; tamResult=tam.startSession(); OR tamResult=tam.startSession(PROTECTED,YES)
Description	The Tamino object attempts to start a transaction session using HTTP/1.1 POST and the _connect verb. A TaminoResult object is returned. Parameters isolation and lockwait mode can be specified optionally. Possible value are: IsolationTypes: "protected","unprotected","shared". In the example constants are used for LockWaitTypes: "yes" or "no" (constants YES or NO can be used)

endSession

Name	endSession
Type	TaminoResult
Example	tamResult=tam.endSession();
Description	The Tamino object attempts to end a transaction session using HTTP/1.1 POST and the _disconnect verb. A TaminoResult object is returned.

commit

Name	commit
Type	TaminoResult
Example	tamResult=tam.commit();
Description	The Tamino object attempts to commit a transaction using HTTP/1.1 POST and the _commit verb. A TaminoResult object is returned.

rollback

Name	rollback
Type	TaminoResult
Example	tamResult=tam.rollback();
Description	The Tamino object attempts to roll back a transaction using HTTP/1.1 POST and the _commit verb. A TaminoResult object is returned.

inSession

Name	inSession
Result Type
Example	if (tam.inSession()) { ... } else { ... }
Description	Returns null if no transaction is in progress, or a non-null value if a transaction is in progress.

Metadata Support

define

Name	define
Result Type	TaminoResult
Example	tam=new TaminoClient("http://mypc.mycompany.com/tamino/xml"); tamResult=tam.define(mySchemaDocumentNode);
Description	Implements the Tamino _define operation. The Tamino URL need only point to a database. An attempt is made to define a Tamino TSD3 schema corresponding to the node instance.

undefine

Name	undefine
Result Type	TaminoResult
Example	tam=new TaminoClient("http://mypc.mycompany.com/tamino/xml"); // undefine the collection and all its doctypes tamResult=tam.undefine("myCollectionName"); or // undefine the doctype within the collection tamResult=tam.undefine("myCollectionName/myDoctype");
Description	Implements the Tamino _undefine operation. The Tamino URL need only point to a database. An attempt is made to undefine a collection or doctype within the specified database. All instances within the doctype(s) described are removed. This works for collections and doctypes defined in TSD3 representation.

Diagnosis

diagnose

Name	diagnose
Result Type	TaminoResult
Example	tamResult=tam.diagnose("ping"); if (tam.Result.errorNo) ... // error detected
Description	The TaminoClient object sends a diagnose command to Tamino. The various commands are documented elsewhere.

explainQuery

Name	explainQuery
Result Type	TaminoResult
Example	tamResult=tam.explainQuery(someQuery); if (tam.Result.errorNo) ... //error detected else { //show explanation panel.innerHTML= tamResult.DOM.documentElement.transformNode(someStylesheet);
Description	The TaminoClient object sends an ino:explain request command to Tamino to retrieve the execution plan of the given query. The parameters are the query expression to be explained and the level of explanation. Please see section ino:explain (Tamino XML Server > X-Query Language Reference > Functions > ino:explain) for a detailed description of ino:explain.

Special Methods requiring filter NodeLevelUpdate.dll

For Microsoft's Internet Information Server (IIS) there is a special filter available, which is a prerequisite for using the following methods of the Tamino API.

insertBefore

Name	insertBefore
Type	TaminoResult
Example	tamResult=tam.insertBefore("/dogs/@2536","dates",DOMnode);
Description	Inserts a child node (third parameter) to the left of the document specified in the relative URL (first parameter) and the query path (second parameter).

appendChild

Name	appendChild
Type	TaminoResult
Example	tamResult=tam.appendChild("dogs/@2536","dates",DOMnode);
Description	Appends a child node (third parameter) as the last child of the document specified in the relative URL (first parameter) and the query path (second parameter).

replaceChild

Name	replaceChild
Type	TaminoResult
Example	tamResult=tam.replaceChild("dogs/@2536","dates/date_of_birth",DOMnode);
Description	Replaces a child node specified by the relative URL (first parameter) and the query path (second parameter) by a new one (third parameter).

removeChild

Name	removeChild
Type	TaminoResult
Example	tamResult=tam.removeChild("dogs/@2536","dates/date_of_birth");
Description	Removes a child node specified by the relative URL (first parameter) and the path (second parameter) .