The following sections describe how to use the various operations that the API provides. All code snippets are written in Visual Basic. To be able to use the predefined constants and receive tool tips, a reference to the ActiveX control must be added to the Visual Basic project. See sampleVBXML for a sample demonstrating the use of the XML ActiveX control.
Methods that take a relative URL will combine the supplied relative URL with the Tamino XML Server base URL to produce an absolute URL that is used to process the programmer's request.
Note that the code snippets that follow make use of the scratch
collection ino:etc
. It should not be used for real
applications.
Before using the API, the ActiveX control must be created and
initialized. This is done by using the Initialize
method and setting the Tamino XML Server base
URL.
... Dim TamX As TaminoX ... Set TamX = CreateObject("TaminoX.TaminoX1") If TamX.Initialize = 0 Then Call MsgBox("TaminoX initialize failed!", vbExclamation) ' exit app End If TamX.csDatabaseURL = "http://localhost/tamino/mydb/ino:etc" ...
The only method that may be used before
Initialize
is UseServerHTTP
.
This is used if a different IXMLHTTPRequest MSXML COM
interface is needed to perform HTTP requests to the Tamino XML
Server. This may be the case if the ActiveX control is being used
from within a server environment.
... Set TamX = CreateObject("TaminoX.TaminoX1") Call TamX.UseServerHTTP (XMLHttpMSXML2Server) If TamX.Initialize = 0 Then Call MsgBox("TaminoX initialize failed!", vbExclamation) ' exit app End If ...
The programmer should use GetErrorStatus
after
methods that are expected to return a result to check for errors. The method
returns an error number and the corresponding error text. If the error number
is zero then no error occurred. If the error number is non-zero then the
corresponding error text should provide more information as to the underlying
reason for the error.
... errNum = TamX.GetErrorStatus(errTxt) If errNum <> 0 Then Call MsgBox(errTxt, vbCritical) End If ...
"sampleVBXML" includes code such as the above example in
the outputError
function.
If an invalid database URL is used in the initialization one would receive an error message of the following form:
Another method that may prove useful in determining the underlying
reason for an error is GetAllResponseHeaders
. This
method returns the concatenation of all the received HTTP headers.
The most direct methods to insert, retrieve and delete documents are
PutDocument
, GetDocument
and
DeleteDocument
. PutDocument
and DeleteDocument
do not normally return a response
document. GetDocument
returns the actual requested
document as the response document. This means that the programmer must
invariably use GetErrorStatus
to check for errors.
... ' xmldoc: <?xml version="1.0"?><Doc><Tag>some text</Tag></Doc> doctype = "Doc" ' document type [root element tag] docname = "Bob" ' document name [programmer specified] relURL = doctype & "/" & docname Call TamX.PutDocument(relURL, xmldoc.DocumentElement) If TamX.GetErrorStatus(errTxt) <> 0 Then Call MsgBox("PutDocument: " & errTxt) Else Set res = TamX.GetDocument(relURL) If TamX.GetErrorStatus(errTxt) <> 0 Then Call MsgBox("GetDocument: " & errTxt) Else Call TamX.DeleteDocument(relURL) If TamX.GetErrorStatus(errTxt) <> 0 Then Call MsgBox("DeleteDocument: " & errTxt) Else Call MsgBox("Put/Get/Delete all worked!") End If End If End If ...
To perform a legacy XQL query, use the DoQuery
method. Use GetResult
to obtain just the result
element of the response. Use ReturnNodes
to obtain the
result element's node list.
... TamX.lPagesize = 2 Set doc = TamX.DoQuery("Doc/Tag") If TamX.GetErrorStatus(errtxt) = 0 Then Set nodelist = TamX.ReturnNodes(doc) MsgBox("NUM NODES: " & nodelist.Length) For Each node In nodelist MsgBox("NODE: " + node.xml) Next End If ...
Note that the methods IsNext/GetNext
and
IsPrevious/GetPrev
can be used to step through
multi-page result sets – see Cursoring for an explanation/example.
To perform an XQuery query, use the XQuery
method. Use XQueryResult
to obtain just the result
element of the response. Use ChildNodes
on the
XQueryResult
response to obtain the result element's
node list.
... Set doc = TamX.XQuery("input()/Doc/Tag") If TamX.GetErrorStatus(errtxt) = 0 Then Set nodelist = TamX.XQueryResult(doc).ChildNodes MsgBox("NUM NODES: " & nodelist.Length) For Each node In nodelist MsgBox("NODE: " + node.xml) Next End If ...
Note that if a transactional session is not in progress the
pagesize
property is ignored and all matching items are
returned in a single response document. If a transactional session is in
progress, a scrollable cursor may be used along with the pagesize
property to split the response documents up into a number of manageable chunks.
The methods IsNext/GetNext
and
IsPrevious/GetPrev
can be used to step through
multi-page result sets – see Cursoring for an explanation/example.
Cursoring permits large query result sets to be split into smaller
manageable chunks. Instead of all matching results being sent as a single
response document, the results can sent as a number of response documents
(pages). Note that cursoring may only be used within a transactional session.
The programmer specifies that cursoring is required by using the
UseRealCursoring
method. The cursor is closed either
at the end of the transactional session or by using the
CloseCursor
method.
... ' use a scrollable cursor Call TamX.UseRealCursoring(RealCursorScrollable) ' start a transactional session to use cursoring Call TamX.StartSession(InoIsolationDefault, InoLockWaitDefault) ' set pagesize for cursor TamX.lPagesize = 2 ' perform XQuery and process results Set doc = TamX.XQuery("input()/Doc/Tag") Set nodelist = TamX.XQueryResult(doc).ChildNodes For Each node in nodelist ... Next ' process subsequent pages While TamX.IsNext(doc) <> 0 Set doc = TamX.GetNext(doc) Set nodelist = TamX.XQueryResult(doc).ChildNodes For Each node In nodelist ... Next Wend ' close the cursor Call TamX.CloseCursor(doc) ' end the transactional session Call TamX.EndSession ...
The API supports the grouping of commands on the Tamino XML Server within transactions. To be able to use grouping transactions the programmer must start a transactional session. Groups of commands may be performed and either committed or rolled back as a group. The programmer must indicate when the transactional session is finished with in order to prevent resource leakage.
... ' start a transactional session Call TamX.StartSession(InoIsolationDefault, InoLockWaitDefault) ' perform some methods ... ' commit all methods Call TamX.Commit ' perform some methods ... ' roll back ALL methods since last commit Call TamX.Rollback ' now end the transactional session Call TamX.EndSession ...
Note that in the "sampleVBXML" error checking is done after each of the above calls. The sample also shows the form of the response documents received by these calls.
To ensure consistency, Tamino XML Server provides a sophisticated locking concept. For detailed information regarding the Tamino locking concept, please refer to the Tamino XML Server documentation. Individual commands outside of a transactional session may have a lock specified or all commands within a transactional session may have a lock specified.
The types IsolationTypes
, LockWaitTypes
and
LockModeTypes
specify the possible values.
Individual commands outside of a transactional session may have a lock specified by using the following methods:
SetIsolationLevel
SetLockWait
SetLockMode
... Call TamX.SetIsolationLevel(requiredIsolation) Call TamX.SetLockWait(requiredLockwait) Call TamX.SetLockMode(requiredLockMode) ... ' perform commands using the specified lock values ...
All commands within a transactional session may have a lock specified by
specifying the lock values in the StartSession
or
BeginSession
methods.
... Call TamX.BeginSession(requiredIsolation, requiredLockwait, requiredLockMode) ... ' do commands using the specified lock values ... Call TamX.EndSession ...
It is possible to vary the timeouts that the Tamino XML
Server will apply to transactions on a connection basis. You can
change the timeout values by using the methods
SetTransactionTimeout
and
SetNonActivityTimeout
.
SetTransactionTimeout
The timeout specifies the maximum amount of time between commit/rollback calls.
SetNonActivityTimeout
The timeout specifies the maximum amount of time between database operations.
Both timeouts are in seconds. If not specified, the timeouts that the Tamino XML Server will use will be the database specific values. These may be viewed/altered by using the Tamino Manager.
... ' set suitable timeouts Call TamX.SetTransactionTimeout(60) Call TamX.SetNonActivityTimeout(30) ... ' perform transactions using the specified timeout values ...
Distributed transactions can be used to group commands associated with different databases. All the commands run within the scope of a distributed transaction.
To participate in a distributed transaction, the Tamino XML
Server needs to know the transaction ID. The transaction ID of
the currently active distributed transaction can either be determined
automatically by the API or it can be explicitly specified by the application.
In either case, the transaction ID is communicated to the Tamino
XML Server. Also, neither form of transaction may use the API
Commit
or Rollback
methods.
If the transaction ID is to be determined automatically, then the
application must be running in the context of a distributed transaction that
implements the Microsoft COM+ interface ITipTransaction. This would be
satisfied by an application running within the MS/DTC (Microsoft's Distributed
Transaction Monitor, which can coordinate commits/rollbacks in different
databases) transactional environment with the application specifying that it
"Requires Transaction" using the MS/DTC console. Note that the
StartSession
/BeginSession
method must execute within the context of the distributed transaction. The
EndSession
method may not be used within an
automatically determined distributed transaction.
The following sample shows the code needed to use an automatically determined transaction:
... ' MS/DTC automatically starts distributed transaction for application ' use distributed transactions Call TamX.UseGlobalTransactions (True) ' automatically pass transaction id to Tamino Call TamX.BeginSession(InoIsolationDefault,InoLockWaitDefault,LockModeDefault) If TamX.GetErrorStatus(errtxt) <> 0 Then MsgBox("ERROR: " & errtxt) End If ... ' do work in context of distributed transaction ... ' do not use EndSession
It is possible that the distributed transaction is explicitly under the
control of the application. If the application wishes to perform Tamino
operations within the context of this distributed transaction, then it must
supply the transaction ID to Tamino via the
BeginSessionWithGlobalTransaction
method. The
EndSession
method may be used if the distributed
transaction has been terminated.
... ' user starts distributed transaction in some manner ' obtain transaction id as TIP URL tipUrl = ... ' pass transaction id to Tamino Call TamX.BeginSessionWithGlobalTransaction(InoIsolationDefault, InoLockWaitDefault, LockModeDefault, tipUrl, TipTransaction) If TamX.GetErrorStatus(errtxt) <> 0 Then MsgBox("ERROR: " & errtxt) End If ... ' do work in context of distributed transaction ... ' user terminates distributed transaction in some manner ' safe to complete transaction Call TamX.EndSession ...
Please note that this filter is a legacy filter provided for backwards
compatibility. The preferred and more powerful way of performing these
operations is to use the XQuery Update
functionality
directly in the Tamino XML Server itself.
For Microsoft's Internet Information Server (IIS) and also for Personal Web Server (PWS) there is a filter available, which you need in case you want to use some special methods of the Tamino DOM APIs.
This filter provides the implementation of the following API methods.
InoAppendChild |
Appends an additional node below a document's node |
InoInsertBefore |
Inserts an additional node before a document's node |
InoReplaceChild |
Replaces one node by another |
InoRemoveChild |
Deletes a node in a document |
Without this special filter you cannot use the above methods. The filter has to be installed in the Internet Information Server. The method calls are intercepted and the filter uses corresponding methods of Microsoft's DOM interface. The filter takes the DOM result objects to communicate then directly to/from the Tamino XML Server (i.e. these methods are not performed directly in the server but within the filter environment on the complete documents).
The following methods may be used to manipulate schema within the
Tamino XML Server: Define
and Undefine
. Define
is used
to define a schema. Undefine
is used to undefine a
schema or a collection.
Warning: Undefining a schema or a collection will cause ALL related data to be deleted! |
... schema.Load("Doc.xsd") Set doc = TamX.Define(schema) MsgBox("Define: " & doc.xml) ... Set doc = TamX.Undefine("Doc") MsgBox("Undefine: " & doc.xml) ...
The following methods may be used for diagnostic purposes:
GetVersion
, Ping
and
Echo
.
... MsgBox("Version: " & TamX.GetVersion) ... Set doc = TamX.Ping MsgBox("Ping: " & doc.xml) ... Set doc = TamX.Echo MsgBox("Echo: " & doc.xml) ...