Tamino DOM Interface

Defines the interface to the Tamino ActiveX control. Please see also the section Command and Response Structure in the chapter X-Machine Programming which is part of the documentation for the Tamino XML server.

Note:
In C++ the properties are accessed using Get/Put method pairs, for example GetProperty/SetProperty.

• BeginSession
• BeginSessionWithGlobalTransaction
• CloseCursor
• Commit
• Define
• DeleteByQuery
• DeleteDocument
• Diagnose
• DoQuery
• DoQueryWithOffset
• Echo
• EndSession
• GetAllResponseHeaders
• GetCollection
• GetDateLastModified
• GetDocType
• GetDocument
• GetErrorStatus
• GetFirst
• GetInoId
• GetLast
• GetLocation
• GetMimeType
• GetNext
• GetPrev
• GetResult
• GetTotalCount
• GetVersion
• GetWarnings
• Head
• InSession
• Initialize
• InoAppendChild
• InoDelete
• InoInsertBefore
• InoRemoveChild
• InoReplaceChild
• Insert
• IsFirst
• IsLast
• IsNext
• IsPrevious
• Ping
• Process
• PutDocument
• PutXML
• RefreshResult
• ReturnNodes
• Rollback
• SetGlobalTransactionId
• SetIsolationLevel
• SetLockMode
• SetLockWait
• SetNonActivityTimeout
• SetTransactionTimeout
• StartSession
• Undefine
• Update
• UseGlobalTransactions
• UseRealCursoring
• UseServerHTTP
• XQuery
• XQueryBytes
• XQueryResult
• XQueryWithOffset

UseServerHTTP

long UseServerHTTP(long index)

Modifies the UseServerHTTP index. This is the only method that may be called before the Initialize method. The default UseServerHTTP index value is 0.

          Possible values are:

0 - Microsoft.XMLHTTP
1 - MSXML2.XMLHTTP
2 - MSXML2.ServerXMLHTTP
3 - MSXML2.XMLHTTP.4.0
4 - MSXML2.ServerXMLHTTP.4.0

Returns:

previous index value

Initialize

long Initialize()

This method should be called before all others except for UseServerHttp.

Returns:

1 - SUCCESS
0 - FAILURE

GetErrorStatus

long GetErrorStatus(VARIANT* ErrorText)

If the last Tamino ActiveX command failed, this command returns the error number and the parameter ErrorText contains the error text. If the command succeeded, the parameter ErrorText contains the Message-Text/Line from Tamino.

Parameters:

VARIANT by reference

Returns:

0 - SUCCESS
not 0 - error number

GetWarnings

long GetWarnings(VARIANT* warnings)

If the last Tamino ActiveX produced warnings in the response document then this command returns the warnings as an array of strings. If one or more warnings are returned then the parameter warnings contains the Message-Text/Line as from Tamino.

Parameters:

VARIANT by reference

Returns:

0 - no warnings
not 0 - number of warnings

GetAllResponseHeaders

BSTR GetAllResponseHeaders()

Retrieves all the HTTP headers from the last Tamino response.

Returns:

Concatenated string of all the HTTP headers.

PutDocument

LPDISPATCH PutDocument(BSTR lpszRelURL, LPDISPATCH lpDOMNode)

Puts a new document node into the Tamino database.

Parameters:

lpszRelURL - NULL, or the relative URL added to the database URL if it does not begin with "http://"

lpDOMNode - IXMLDOMNode

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

GetDocument

LPDISPATCH GetDocument(BSTR lpszRelURL)

Returns the document specified by the lpszRelURL parameter.

Parameter:

lpszRelURL - NULL, or the relative URL added to the database URL if it does not begin with "http://"

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

DeleteDocument

LPDISPATCH DeleteDocument(BSTR lpszRelURL)

Deletes the document specified by the lpszRelURL parameter.

Parameter:

lpszRelURL - NULL, or the relative URL added to the database URL if it does not begin with "http://"

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

PutXML

LPDISPATCH PutXML(BSTR lpszReURL, VARIANT xmlBytes)

Put the specified XML document into Tamino. Allows documents with "exotic" encodings to be placed into Tamino without being first loaded by the MSXML parser.

Parameters:

lpszRelUrl - NULL, or the relative URL added to the database URL if it does not begin with "http://"

xmlBytes - XML document as byte array (SAFEARRAY of VT_UI1)

Returns:

NULL or IXMLDOMDocument for the response document

Process

LPDISPATCH Process(LPDISPATCH lpDOMNode, BSTR lpszProcURL)

Inserts or updates the node lpDOMNode in the database.

Parameters:

IXMLDOMNode - IXMLDOMNode

lpszProcURL - NULL or the relative URL added to the database URL

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

InoDelete

LPDISPATCH InoDelete(LPDISPATCH lpDOMElement)

Deletes a DOM element from the Tamino database.

Parameters:

IXMLDOMElement

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

Insert

LPDISPATCH Insert(LPDISPATCH lpDOMNode)

Inserts a new node lpDOMNode into the Tamino database.

Parameters:

IXMLDOMNode

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

DoQuery

LPDISPATCH DoQuery(BSTR lpszXQLQuery)

Queries the Tamino database with lpszXQLQuery statement.

Parameter:

lpszXQLQuery - query expression

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

See also:

RefreshResult()

DoQueryWithOffset

LPDISPATCH DoQueryWithOffset(BSTR lpszXQLQuery, long loffset)

Queries the Tamino database with lpszXQLQuery statement.

Parameters:

lpszXQLQuery - query expression

loffset - offset at which the query starts

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

See also:

RefreshResult(), DoQuery()

RefreshResult

LPDISPATCH RefreshResult()

Repeats the last query.

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

See also:

DoQuery()

GetResult

LPDISPATCH GetResult(LPDISPATCH lpDOMDocument)

Queries for xql:result element in lpDOMDocument.

Parameters:

IXMLDOMDocument

Returns:

IXMLDOMElement

ReturnNodes

LPDISPATCH ReturnNodes(LPDISPATCH lpDOMDocument)

Queries DOM document for xql:result and returns child nodes. It implicitly calls GetResult.

Parameters:

IXMLDOMDocument

Returns:

IXMLDOMNodeList

IsPrevious

long IsPrevious(LPDISPATCH lpDOMDocument)

Checks if a GetPrev() method call is possible.

Parameters:

IXMLDOMDocument

Returns:

1 - TRUE
0 - FALSE

See also:

GetPrev()

GetPrev

LPDISPATCH GetPrev(LPDISPATCH lpDOMDocument)

Retrieves the previous page of query results.

Parameters:

IXMLDOMDocument

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

See also:

IsPrevious()

IsNext

long IsNext(LPDISPATCH lpDOMDocument)

Checks if a GetNext() method call is possible.

Parameters:

IXMLDOMDocument

Returns:

1 - TRUE
0 - FALSE

See also:

GetNext()

GetNext

LPDISPATCH GetNext(LPDISPATCH lpDOMDocument)

Retrieves the next page of query results.

Parameters:

IXMLDOMDocument

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

See also:

IsPrevious()

IsFirst

long IsFirst(LPDISPATCH lpDOMDocument)

Checks if a GetFirst() method call is possible.

Parameters:

IXMLDOMDocument

Returns:

1 - TRUE
0 - FALSE

See also:

GetFirst()

GetFirst

LPDISPATCH GetFirst(LPDISPATCH lpDOMDocument)

Retrieves the first page of query results.

Parameters:

IXMLDOMDocument

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

See also:

IsFirst()

IsLast

long IsLast(LPDISPATCH lpDOMDocument)

Checks if a GetLast() method call is possible.

Parameters:

IXMLDOMDocument

Returns:

1 - TRUE
0 - FALSE

See also:

GetLast()

Note:

This method is deprecated with Tamino Version 2.1 and above.

GetLast

LPDISPATCH GetLast(LPDISPATCH lpDOMDocument)

Retrieves the last page of query results.

Parameters:

IXMLDOMDocument

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

See also:

IsLast()

Note:

This method is deprecated with Tamino Version 2.1 and above.

GetTotalCount

long GetTotalCount(LPDISPATCH lpDOMDocument)

After a query it returns the count of elements.

Parameters:

IXMLDOMDocument

Returns:

long

See also:

DoQuery()

Note:

This method is deprecated with Tamino Version 2.1 and above.

DeleteByQuery

LPDISPATCH DeleteByQuery(BSTR lpszQuery, BSTR lpszCollection, BSTR lpszDocType)

Delete by query with collection name and doctype name in the query string.

The Tamino object attempts to delete all documents that are described by the query. If the collection is set, be sure that the baseURL does not contain the collection name, otherwise an error will occur.
Note: From Tamino Version 2.1 onwards, the collection must be added to the baseURL.

Parameters:

lpszQuery - query expression to select records to delete

lpszQueryCollection - collection name

lpszQueryDocType - doctype name

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

XQuery

LPDISPATCH XQuery(BSTR lpszXQuery)

Perform an XQuery request.

Parameters:

lpszQuery - a correctly formatted XQuery string

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

XQueryWithOffset

LPDISPATCH XQuery(BSTR lpszQuery, long offset)

Perform an XQuery command starting reading at specified position.

Parameters:

lpszQuery - a correctly formatted XQuery string
offset - position to start reading from

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

XQueryResult

LPDISPATCH XQueryResult(LPDISPATCH lpDOMDocument)

Returns the XQuery result element of the specified response document.

Parameters:

lpDOMDocument - XQuery response document

Returns:

IXMLDOMElement: result element or NULL if not found

XQueryBytes

long XQueryBytes(BSTR lpszXQuery, VARIANT* bytes)

Performs the specified XQuery and returns the result as a byte array. This method is intended for queries that return documents that are not of the type "text/xml". Use GetMimeType to obtain the MIME type of the query response.

Parameters:

lpszQuery - a correctly formatted XQuery string
bytes - to hold result of query as a byte array

Returns:

length of byte array returned

Update

LPDISPATCH Update(BSTR lpszUpdate)

Perform an XQuery update request.

Parameters:

lpszUpdate - a correctly formatted XQuery update string

Returns:

DOM tree corresponding to response [if NULL use GetErrorStatus]

UseRealCursoring

long UseRealCursoring(RealCursorTypes index)

To indicate whether real cursors should be used for queries.

Parameters:

index - RealCursorTypes value.
One of:
NoRealCursor = 0,
RealCursorNonScrollable = 1,
RealCursorScrollable = 2

Returns:

Previous setting of UseRealCursoring index.

CloseCursor

LPDISPATCH CloseCursor(LPDISPATCH lpDOMDocument)

Close the specified cursor. This must be done when a query has been finished with. The cursor must be closed to release resources.

Parameters:

lpDOMDocument - DOM document with cursor

Returns:

NULL or IXMLDOMDocument for the response document

StartSession

LPDISPATCH StartSession(IsolationTypes InoIsolation, LockWaitTypes InoLockWait)

Starts a new transactional session.
BeginSession should be used in preference to this method.

Parameters:

IsolationTypes - This is one of the following:
   InoIsolationDefault = 1 (take the default defined in Tamino),
   InoUnprotected = 2,
   InoShared = 3,
   InoProtected = 4

LockWaitTypes - This is one of the following:
   InoLockWaitDefault = 1 (take the default defined in Tamino),
   InoLockWaitYes = 2,
   InoLockWaitNo = 3

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

Commit

LPDISPATCH Commit()

Commits the transaction.

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

Rollback

LPDISPATCH Rollback()

Rolls back the transaction.

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

EndSession

LPDISPATCH EndSession()

Finishes the transactional session.

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

InSession

long InSession()

Indicates whether a transactional session is in progress or not.

Returns:

TRUE or FALSE

UseGlobalTransactions

long UseGlobalTransactions(long flag)

Automatically use declarative DTC transactions or not.
This flag is TRUE by default.

Parameters:

flag - TRUE or FALSE

Returns:

previous value

SetGlobalTransactionId

LPDISPATCH SetGlobalTransactionId(VARIANT id, GlobalTransactionTypes type)

Parameters:

id - BSTR for TipTransaction, BYTE[64] for UtxIdTransaction, BSTR for UtxUrlTransaction

type - This is one of the following:
   TipTransaction = 1,
   UtxIdTransaction = 2
   UtxUrlTransaction = 3

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

BeginSession

LPDISPATCH BeginSession(IsolationTypes isolation, LockWaitTypes wait, LockModeTypes mode)

Begin a transactional session using the specified command modifiers for the transaction.

Parameters:

isolation - see SetIsolationLevel for possible values

wait - see SetLockWait for possible values

mode - see SetLockMode for possible values

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

BeginSessionWithGlobalTransaction

LPDISPATCH BeginSessionWithGlobalTransaction(IsolationTypes isolation, LockWaitTypes wait, LockModeTypes mode, VARIANT id, GlobalTransactionTypes type)

Begin a transactional session using the specified global transaction id and the specified command modifiers for the transaction.

Parameters:

isolation - see SetIsolationLevel for possible values

wait - see SetLockWait for possible values

mode - see SetLockMode for possible values

id - see SetGlobalTransactionId for possible values

type - see SetGlobalTransactionId for possible values

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

SetIsolationLevel

long SetIsolationLevel(long isolation)

Set new isolation level command modifier for all subsequent commands.

Parameters:

isolation - This is one of the following:
   InoIsolationDefault = 1 (take the default defined in Tamino),
   InoUnprotected = 2,
   InoShared = 3,
   InoProtected = 4,
   IsolationUncommittedDocument = 5,
   IsolationCommittedCommand = 6,
   IsolationStableCursor = 7,
   IsolationStableDocument = 8,
   IsolationSerializable = 9

Returns:

previous value

SetLockWait

long SetLockWait(long wait)

Set new lockwait command modifier for all subsequent commands.

Parameters:

wait - This is one of the following:
   InoLockWaitDefault = 1 (take the default defined in Tamino),
   InoLockWaitYes = 2,
   InoLockWaitNo = 3

Returns:

previous value

SetLockMode

long SetLockMode(long mode)

Set new lockmode command modifier for all subsequent commands.

Parameters:

mode - This is one of the following:
   LockModeDefault = 1 (take the default defined in Tamino),
   LockModeUnprotected = 2,
   LockModeShared = 3,
   LockModeProtected = 4

Returns:

previous value

SetTransactionTimeout

long SetTransactionTimeout(long secs)

Set new transaction timeout for all subsequent StartSession/BeginSession method calls.

Parameters:

secs - This is one of the following:
   -1 = As long as the transactional session lasts
   0 = Use Tamino default
   >0 = Use specified value

Returns:

previous value

SetNonActivityTimeout

long SetNonActivityTimeout(long secs)

Set new non-activity timeout for all subsequent StartSession/BeginSession method calls.

Parameters:

secs - This is one of the following:
   0 = Use Tamino default
   >19 = Use specified value

Returns:

previous value

InoAppendChild

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

LPDISPATCH InoAppendChild(BSTR lpszRelURL, BSTR lpszXPath, BSTR lpDOMNode)

Appends a child node as the last child of the document specified in lpszRelURL.

As a prerequisite, the Tamino IIS filter (NodeLevelUpdate.dll) must be installed.

Parameters:

lpszRelURL - relative URL to the document

lpszXPath - path expression leading to the node

lpDOMNode - new node to append

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

InoInsertBefore

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

LPDISPATCH InoInsertBefore(BSTR lpszRelURL, BSTR lpszXPath, BSTR lpDOMNode)

Inserts a child node to the left of the document specified in lpszRelURL.

As a prerequisite, the Tamino IIS filter (NodeLevelUpdate.dll) must be installed.

Parameters:

lpszRelURL - relative URL to the document

lpszXPath - path expression leading to the node

lpDOMNode - new node to append

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

InoReplaceChild

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

LPDISPATCH InoReplaceChild(BSTR lpszRelURL, BSTR lpszXPath, BSTR lpDOMNode)

Replaces the child node specified by lpszRelURL and lpszRelURL by a new one.

As a prerequisite, the Tamino IIS filter (NodeLevelUpdate.dll) must be installed.

Parameters:

lpszRelURL - relative URL to the document

lpszXPath - path expression leading to the node

lpDOMNode - new node to append

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

InoRemoveChild

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

LPDISPATCH InoRemoveChild(BSTR lpszRelURL, BSTR lpszXPath)

Removes the child node specified by the parameters.

As a prerequisite, the Tamino IIS filter (NodeLevelUpdate.dll) must be installed.

Parameters:

are generated by the connection layer

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

Undefine

LPDISPATCH Undefine(BSTR theSchema)

Erases an existing doctype (schema) or a collection of doctypes.

Parameters:

BSTR

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

Define

LPDISPATCH Define(LPDISPATCH lpDOMDocument)

Creates a new doctype (schema) or a collection of doctypes.

Parameters:

IXMLDOMDocument

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

Diagnose

LPDISPATCH Diagnose(BSTR what)

Fetches a response from the Tamino server. Possible responses to fetch are "ping", "echo", "version" and "fullVersion".

Parameters:

what - what response to fetch

Returns:

IXMLDOMElement

Echo

LPDISPATCH Echo()

Returns a positive response (a pre-defined string) if the inner X-Machine layer is reachable by the connection layer. Otherwise an error message is generated by the connection layer.

Returns:

IXMLDOMElement

Ping

LPDISPATCH Ping()

Establishes an HTTP connection and returns a positive answer (something like "Database ID=099 is alive") in case of success.

Returns:

IXMLDOMElement

GetVersion

BSTR GetVersion()

Retrieves the current Tamino version. Note: With Tamino Version 1.x, the returned value is empty.

Returns:

BSTR

Head

LPDISPATCH Head(BSTR lpszRelURL)

Returns the head of the document specified by the lpszRelURL parameter.

Parameters:

lpszRelURL - NULL, or the relative URL added to the database URL if it does not begin with "http://"

Returns:

IXMLDOMDocument: DOM tree corresponding to response [if NULL use GetErrorStatus]

GetMimeType

BSTR GetMimeType()

Retrieves the response header "Content-Type" from the last HTTP request.

Returns:

BSTR

GetDateLastModified

BSTR GetDateLastModified(BSTR lpszRelURL)

Returns the value of the last HTTP header "Last-Modified" of the document specified in the lpszRelURL parameter.
Example: Tue, 16 May 2000 08:26:56 GMT

Parameter:

lpszRelURL

Returns:

BSTR

GetLocation

BSTR GetLocation(LPDISPATCH lpDOMDocument)

Retrieves the response header "Location" from the previous HTTP request. "Location" is the URL at which data is updated or inserted.

Parameters:

IXMLDOMDocument

Returns:

BSTR

GetCollection

VARIANT GetCollection(LPDISPATCH lpDOMX)

Receives the collection of the lpDOMX parameter.

Parameter:

lpDOMX - IXMLDOMElement or IXMLDOMDocument

Returns:

VARIANT

GetDocType

VARIANT GetDocType(LPDISPATCH lpDOMX)

Receives the document type of the lpDOMX parameter.

Parameter:

lpDOMX - IXMLDOMElement or IXMLDOMDocument

Returns:

VARIANT

GetInoId

VARIANT GetInoId(LPDISPATCH lpDOMX)

Receives the ino:id of the lpDOMX parameter.

Parameter:

lpDOMX - IXMLDOMElement or IXMLDOMDocument

Returns:

VARIANT

www.softwareag.com

© Copyright Software AG 1999-2004. All rights reserved.