
HTTP Client API for JScript	Version 9.7	SEARCH INDEX CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— HTTP Client API for JScript —

TaminoClient

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");

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

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`.

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

Note:
An initial putBinary request should work without a problem. Subsequent putBinary requests that are attempting to update an existing document will cause the API to hang. This appears to be a problem with the XMLHTTP interface not handling an HTTP 204 response correctly. The suggested workaround is to delete the document before attempting the insert.

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.

Note:
The use of the NodeLevelUpdate ISAPI has been set to deprecated.

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) .

SEARCH INDEX CONTENTS | PDF BOOKS | HOME UP PREV NEXT