The information in this document is broken down as follows:
Tamino server extensions follow the object oriented approach. From this point of view, server extensions are objects and server extension functions are their methods.
One server extension object may have an arbitrary number of server extension functions as methods. These can also be functions of different types.
Server extensions have constructors and destructors. In Direct/C++ and Java server extensions, the standard constructors and destructors that are provided with the programming language are used.
Tamino server extensions can have member variables. In programming languages that support object orientation, they are handled in the usual way.
A Tamino server extension object is created when one of its methods is used for the first time. The object lasts for the duration of the associated XML session. In the case of an anonymous session, the object lasts for the duration of the associated transaction or request.
Tamino X-Tension supports the following server extension function types according to the context of execution:
that are explicitly called from within X-Query queries;
that are used for executing functions when storing or deleting a related document independent of mapping;
that are used to create index values for non-XML documents as a shadow of the original;
that are used for storing, retrieving, or deleting documents and called by Tamino document processing, composing or on delete;
that allow initializing functions to be executed on the server extension object prior to any query, trigger or mapping function execution;
that ensure transaction consistency.
A server extension can contain multiple mapping, trigger, shadow and query functions, but at most one initial function and one server event function. Usually, mapping functions appear as a complete set (one map in function, one map out function, one delete function and one event function that handles at least the commit and rollback events).
Note:
All server extension function types are supported for all X-Tension
infrastructures. Implementation-specific details are indicated where
appropriate.
A single server extension can contain multiple server extension functions.
The function name must be unique within the Tamino database. If a Tamino
Server includes several server extensions, the function name defined in the
source code, the "internal name", may not be unique. Therefore
when a server extension is installed, each function is given a unique
"external name". By default, the external name is the
dot-separated concatenation of the server extension name and the function's
internal name, for example: MyExtension.FirstFunction. If a name
conflict occurs, the Tamino X-Tension Object Analyzer can be used to change the
external function name. For query extension functions, it is even possible to
change the external name after installation, using the Tamino Manager. Such
functions will often be called directly by Tamino database users, so for the
convenience of XQuery users we recommend changing the functions' external names
immediately after installation to short, easily remembered names.
Query functions are used to extend Tamino's query languages XQuery and X-Query. You can define shortcuts for complex queries and create custom-defined filters. Multiple query functions can be contained in a single server extension object.
The information about query functions is broken down into the following sections:
A query function has zero or more "in" parameters and exactly one return value.
A query function has n parameters and one return value.
The XML data types allowed for the parameters and the return value and their equivalents in Direct and Java are shown in the following table:
| XML | Direction | Direct/C++ | Java |
|---|---|---|---|
| xs:boolean | in | sxdbool | boolean |
| xs:boolean | return value | sxdbool * | boolean |
| xs:string | in | sxdstring | String |
| xs:string | return value | sxdstring * | String |
| xs:double | in | sxddouble | double |
| xs:double | return value | sxddouble * | double |
| xs:float | in | sxdfloat | float |
| xs:float | return value | sxdfloat * | float |
| xs:int | in | sxdint | int |
| xs:int | return value | sxdint * | int |
| ino:XML-OBJ | in | sxdstring | String |
| ino:XML-OBJ | return value | sxdstring * | String |
Use the ByVal attribute for input parameters.
Reference parameters (i.e. without the ByVal attribute) are always input/output.
Retval parameters are real return values, e.g.:
Function SXSEvent(ByVal status As Long) As Long
SXSEvent = 0
End Function
No HRESULT parameter.
A server extension with a retval parameter is implemented as a Function.
A server extension without a retval parameter is implemented as a Sub.
A query function is called as part of an X-Query/XQuery request using its external name (see the section Function Naming). The parameters are passed as a list, separated by commas and enclosed in parentheses. String constants must be enclosed in quotation marks. The calling syntax is independent of the infrastructure and language.
Syntax:
<external function name> ( [ <parameter> { [ , <parameter> ] } ] )
Examples:
MyFunc('Input-String', 13)
MyFunc(/a/b, count(/c/d))
Notes:
As shown in the example in the section Query Function Call Syntax, parameters can be passed as constants or expressions. These expressions again can contain query functions: built-in functions or server extension functions.
First, expressions are evaluated, then they are converted into the data type required by the function if possible, and finally they are passed to the function. If it is not possible to convert an expression, a runtime error occurs.
Parameters are converted according to the rules defined by the W3C specification for the conversion of query function parameters.
For example, if the result of a query expression, a node set, is passed
as a parameter of the data type string, this is done as if the built-in query
function string() were applied to the query expression. This
returns the string content of the node set's first XML node. If the result of
the same query expression were passed as a parameter of the data type XML
Object, the result would be a completely different value, namely the whole node
set in its string representation.
Caution:
If the quotation marks are omitted for a string constant, the
Tamino Server attempts to evaluate the string as a query expression. This can
produce erroneous results that are very difficult to interpret.
Even return values are converted if possible. Special attention must be paid to the data type XML Object. For this data type a syntactically correct string representation of a node set must be returned. There is one exception: a simple string can also be processed if it does not contain XML tags or angle brackets.
Query functions can appear at different locations within an X-Query expression. The data type of a query function's return value must be valid at the place where the query function is located within the query expression. The different possible locations are discussed in the following:
This is as if a query function were entered instead of an XML query.
Examples:
MySubString('abcdefg',2,4)
MyFunc('Hello',/a/b,12)
At such a location, the function is evaluated once and the return value is inserted into the Tamino response document. The return value can have any of the data types specified in the table in the section Query Function Parameters and Data Types.
If a parameter is a query expression, the expression is evaluated and the resulting node set is passed as a parameter (after conversion, if necessary).
In the second example, nodes "b" in the node set of all documents of document type "a" are passed to MyFunc as the second parameter.
Example:
/a/b[name~=MyFunc('Hello', c/d,4)]
For such a call, the data type of the function's return value must be convertible into the type required by the filter expression.
The function is called as often as required by the number of nodes found by the query /a/b. The return value is inserted into the filter expression to be evaluated there.
A query expression as parameter is evaluated relative to the context.
Let /a/b in the example above result in a node set of
three nodes: n1, n2
and n3. The function is called three times. As the
second parameter, Tamino passes each time a part of the node set
/a/b/c/d: at the first call the part lying under
n1, at the second call the part lying under
n2 and at the third call the part under
n3. After each function call the return value of
MyFunc is compared with name of the current node,
and the result decides whether it will be part of the result document or
not.
If a query expression with an absolute path as the parameter specification is evaluated, the whole of the document which contains the current node from whence the function was called is scanned.
Example:
/a/b[firstname~=MyFunc('Hello', /a/b/c/d,4)]
The MyFunc function is called as often as elements
b of document type a
are available. For each single function call, only the current document
a is considered when evaluating the second
function parameter.
XML documents or elements contained in XML documents can be associated with a function which is executed using the sub-node's content, but independent of mapping. Moreover, the result of the function can influence the result of the request, but it may not alter the document's structure or content. There are three types of trigger functions:
For storage or processing: the Insert Trigger,
which is executed after the validation phase during processing;
For updating: the Update Trigger,
which is executed after the validation phase during the updating of an XML document;
For deletion: the Delete Trigger,
which is executed when an XML document is to be deleted from the database.
Note:
If an X-Machine _process command
specifying the ino:id or
ino:docname of an existing document is used in
order to replace the existing document, Tamino uses the update trigger twice
rather than using a delete trigger followed by an insert trigger. This is
indicated below for the situation The document update changes a node
"A" under the Execution heading of the
Update Trigger
section.
Multiple triggers can be contained in a single server extension. Depending on the action to be performed, you can include a complete set of trigger functions (one insert trigger, one update trigger and one delete trigger) in a server extension, but this is not mandatory.
Triggers can only be executed if they have been associated with schemas after installing the server extension package in a Tamino database. Insert, update and delete triggers that propagate errors by using the exception mechanism cause the current request to fail and thus prevent the whole document from being successfully stored, retrieved or deleted. The sequence of execution when multiple triggers are used is undefined and can vary according to the request content, optimization or Tamino version. Nevertheless, the trigger is called only if the request has been successfully executed so far. Subsequent request execution may fail and the server extension's event function is notified. See the section Tamino Server Extension Examples for information about sample mapping programs.
The Tamino Server calls trigger functions when an XML document with a schema containing a trigger set to "Action/onInsert" is to be stored by the Tamino Server.
The part of a document that is associated with the trigger is passed to the server extension function, along with administrative information.
An insert trigger function has four input parameters whose data types are as follows:
| Position | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 | collection | xs:string | sxdstring | string |
| 2 | doctype | xs:string | sxdstring | string |
| 3 | ino:id | xs:string | sxdstring | string |
| 4 | XML Object | ino:XML-OBJ | sxdstring | string |
The collection, the
doctype and the ino:id of the
document are passed for information to the server extension function. The
information may not be persistent, as the subsequent request execution may be
erroneous and the document may not be stored.
The XML Object represents the (part of the)
document to be processed and therefore contains its string representation.
An insert trigger function may be used to verify the respective part of the document or to act upon its content.
An insert trigger is only executed if the document node contains a value or if there is a default value. If an optional node is not available or the document node is empty and there is no default value, the trigger function is not executed. Insert triggers are executed before any mapping takes place. If a default value is defined, a map-in function is called.
The Tamino Server calls an update trigger function when an XML document with a schema containing a trigger set to "Action/Update" (update trigger) is to be updated by the Tamino Server. An update trigger function has five input parameters, whose data types are as follows:
| Position / Direction | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 / in | collection | xs:string | sxdstring | string |
| 2 / in | doctype | xs:string | sxdstring | string |
| 3 / in | ino:id | xs:string | sxdstring | string |
| 4 / in | XML Object old state | ino:XML-OBJ | sxdstring | string |
| 5 / in | XML Object new state | ino:XML-OBJ | sxdstring | string |
The collection, the
doctype and the ino:id of the
document are passed for information to the server extension function in every
calling context. This is the information that was used to retrieve the part of
the document. The XML Object old state represents the
(part of the) document before the update and contains its string
representation. The XML Object new state represents the
(part of the) document after the update and contains its string representation.
Update trigger functions may be used to perform some action based upon the
updating of a document.
There are different update situations, which influence the execution
behavior of the trigger and the parameters passed to it. Let there be a node
A in the schema, which is related to an update
trigger. Let this node A contain
sub-documents.
The document is updated in a sub-document of
A but A itself
remains unchanged.
The update trigger is executed for each altered
A, with "XML Object old state" and
"XML Object new state" representing the node
A and its sub-document before and after the
update.
The document update removes a node
A.
The update trigger is executed once for each removed
A, with "XML Object old state"
representing the node A before its removal and
"XML Object new state" being NULL.
The document update creates a node
A.
The update trigger is executed once for each inserted
A, with "XML Object old state" being
NULL and "XML Object new state" representing the node
A after its insertion.
The document update changes a node
A.
The update trigger is executed twice for each altered
A. The first time, "XML Object old
state" represents the node A before the
update and XML Object new state is NULL. The
second time, "XML Object old state" is NULL and "XML Object
new state" represents the node A after the
update.
This behavior reflects the flexibility of XML update, which allows updating documents in the above mentioned situations for one or more nodes in one request.
Delete triggers are called when an XML document is to be deleted from the Tamino Server.
The Tamino Server calls trigger functions when an XML document with a schema containing a trigger set to "Action/onDelete" is to be deleted by the Tamino Server.
The part of a document that is associated with the trigger is passed to the server extension function, along with administrative information.
A delete trigger function has the same four parameters as an insert trigger function. The data types are as follows:
| Position | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 | collection | xs:string | sxdstring | string |
| 2 | doctype | xs:string | sxdstring | string |
| 3 | ino:id | xs:string | sxdstring | string |
| 4 | XML Object | ino:XML-OBJ | sxdstring | string |
The collection, doctype
and ino:id of the document are passed for information to
the server extension function. This information is used to retrieve the part of
the document for deletion.
The XML Object represents the (part of the)
document to be deleted and contains its string representation.
Delete trigger functions may be used to validate the deletion of a document or to act upon the content to be removed.
Delete triggers are only executed if the document node contains a value. If an optional node is not available or if the document node is empty, the trigger function is not executed.
See the section Tamino Server Extension Examples for information about programming examples.
A shadow function is used to create a shadow document in
Tamino for a non-XML document that can be stored in Tamino or in an external
location. If tsd:storeShadowOnly is defined in the
schema, the shadow document is stored in Tamino but the non-XML document is not
copied into Tamino.
A shadow document is an XML document, generated using user-written logic, that can contain information such as metadata, index values and other generated values for the corresponding non-XML document. The purpose of the shadow document is to store information that can be used for queries that would not be possible on the original non-XML document.
The schema that defines the non-XML document must also contain appropriate schema statements to indicate that a shadow function will be used. See the discussion on Using Shadow Functions in the section Storing Non-XML Objects in Tamino in the Tamino XML Schema User Guide for details. When Tamino processes the non-XML document, the instance is passed as a parameter of binary or textual data type to the shadow function, which builds the shadow document. This shadow document is then passed to the X-Machine for further inserting and index processing. The result is stored as a shadow of the original non-XML document.
The general rules covering the behavior of shadow documents and the original non-XML documents are as follows:
When an XQuery or X-Query query is issued, Tamino examines the shadow documents and not the non-XML documents.
If the non-XML document is stored in Tamino and a delete command is issued to delete the document, Tamino deletes both the shadow document and the non-XML document.
When an existing non-XML document is replaced (i.e. old document removed and replaced by a new one), the corresponding shadow document is deleted and a new shadow document is created.
Shadow documents cannot be updated or deleted by using
xquery update or xquery
delete commands.
If plain URL addressing is used for retrieval, Tamino returns the non-XML document and not the shadow document. If the non-XML document is stored outside Tamino, an HTTP status 404 (file not found) is returned. For details of plain URL addressing, see the section Requests using Plain URL Addressing in the X-Machine Programming guide).
A shadow function can be implemented in any programming language that is supported by X-Tension, using any supported infrastructure. Like mapping functions and trigger functions, a shadow function has a defined signature and a restricted execution context (here it is limited to insertion of non-XML documents).
A shadow function can be part of any server extension's object. Its execution is part of the request, transaction and session processing, like the execution of a mapping function or trigger function.
The non-XML document that corresponds to the shadow function can contain pure text or "real" binary content, so the shadow function type comes with two kinds of signatures, which are called according to the actual content of the document. Tamino determines whether a non-XML document should be treated as a text document or a binary document solely on the basis of the document's media type (see the section Media Type Requirements in the X-Machine Programming guide for details). Thus, for example, Tamino stores base64-coded binary objects as text or binary objects depending on the media type setting.
Shadow functions related to the node of onTextInsert are defined with the following parameter structure:
| Position / Direction | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 / in | collection | xs:string | sxdstring | string |
| 2 / in | doctype | xs:string | sxdstring | string |
| 3 / in | doctypeURL | xs:string | sxdstring | string |
| 4 / in | ino:id | xs:string | sxdstring | string |
| 5 / in | ino:docname | xs:string | sxdstring | string |
| 6 / in | non-XML-Text | xs:string | sxdstring | string |
| 7 / retval | Shadow-XML | ino:XML-OBJ | sxdstring | string |
Shadow functions related to the node of onBinaryInsert are defined with the following parameter structure:
| Position / Direction | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 / in | collection | xs:string | sxdstring | string |
| 2 / in | doctype | xs:string | sxdstring | string |
| 3 / in | doctypeURL | xs:string | sxdstring | string |
| 4 / in | ino:id | xs:string | sxdstring | string |
| 5 / in | ino:docname | xs:string | sxdstring | string |
| 6 / in | non-XML-Binary | ino:Binary | sxdstring | Byte Array |
| 7 / retval | Shadow-XML | ino:XML-OBJ | sxdstring | string |
When Tamino processes a non-XML document, it accepts any type of input (text in any format, binary data of any kind) from the calling context as an input parameter and delivers it without change to the shadow function. The XML schema data types xs:hexBinary and xs:base64Binary as defined in xmlschema-2 do not serve this purpose because they use encoding (hex or base64) with conversion procedures. Therefore the Tamino data type ino:Binary has been designed. Its values are handed to the shadow function (binary type) in its language dependent representation.
XML documents or elements of them can be stored native, i.e. "as-is", in the Tamino database, or using the X-Node.
In addition, a more dynamic kind of mapping can be performed using Tamino server extensions: the "Mapping to Function". XML documents or parts of them are passed to or taken from a user-defined mapping function. In this case, mapping functions must be used to handle the sub-document completely.
There are three types of mapping functions:
One for storage or processing: the map-in function,
which is executed when mapping the verified document;
one for retrieval or composition: the map-out function,
which is executed when retrieving the document nodes; and
one for deletion: the map-delete function,
which is executed when an XML document is to be deleted from the database.
Multiple mapping functions can be contained in a single server extension. Usually you should include a complete set of mapping functions (one map-in function, one map-out function and one delete function) in a server extension.
Mapping functions can only be executed if they have been associated with schemas after installing the server extension package in a Tamino database. Mapping server extension functions which propagate errors cause the current request to fail, and thus prevent the whole document from being successfully stored, retrieved or deleted.
The sequence of execution of mapping functions and server extensions is undefined and can vary according to the request content, optimization or Tamino version. Nevertheless, the mapping function is called only if the request has been successfully executed so far. Subsequent request execution may fail and the server extension's event function is notified.
See the section Tamino Server Extension Examples for information about sample mapping programs.
Map-in functions are called by the Tamino Server when an XML document
is stored by the Tamino Server. The map-in function is called for the part of
the document where the associated schema storage type is set to
"Map XTension" and the
onProcess property is defined.
The part of the document that is mapped to a server extension function is passed to the server extension function, along with administrative information.
A map-in function has three or four parameters, whose data types are as follows:
| Position / Direction | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 / in | Object ID | xs:int | sxdint | int |
| 2 / in | Element ID | xs:int | sxdint | int |
| 3 / in | XML Object | ino:XML-OBJ | sxdstring | String |
| 4 (optional) / out | Node Info | xs:string | sxdstring * | StringBuffer |
The Object ID and Element
ID are used to uniquely identify the data that is passed to the
server extension function in the specific database.
The XML Object represents the (part of the)
document to be processed and already validated. It contains the string
representation of a well-formed XML document or fragment.
The optional fourth parameter can be used by the server extension function to store arbitrary information in the Tamino database, which can only be accessed in a successive map-in or map-delete server extension function.
Map-in functions may be used to store those parts of an XML document
that are mapped to a server extension function outside of the Tamino database.
The Object ID and Element ID are
database-specific keys, given from the Tamino Server. No semantic is associated
with them.
The Node Info can be used to conveniently store
customer-specific information about where the data is stored, for example the
name of a file in which the data is stored, or an SQL command that delivers the
data as a result, if it is stored in a third party relational database.
The Node Info is transparent to the Tamino
Server and is only interpreted by corresponding map-out and delete functions if
specified by the Tamino server extension developer. The fourth parameter is
optional. However, if the function does not support this parameter, there is no
way in which node information can be stored or used.
Note:
Remember to define a corresponding map-out function for each map-in
function you develop, otherwise you will not be able to retrieve the data
stored with your map-in function.
Although Object ID and Element
ID uniquely identify the subdocument within a single Tamino Server,
you should take the following into consideration when designing the key for
storing, retrieving and deleting the mapped data:
Object ID and Element
ID may change when the database is unloaded/loaded, for example
when the Tamino Data Loader is used for mass loading and unloading of data. The
Node Info is invariant under massload.
Object ID, Element ID
and Node Info remain unchanged when the database
undergoes backup or restore/recovery processes.
Different databases may use the same internal keys.
The database name may change as the result of a Tamino Administrator
rename database command.
You should consider defining a key independent of Object
ID, Element ID and database-name and keeping
it in the Node Info parameter of the map-in function,
where it can be used in all other cases of mapping.
Map-in functions are only executed if the document node contains a value. If an optional node is not available or the document node is empty, the map-in function is not executed.
See the section Tamino Server Extension Examples for information about programming examples.
Map-out functions are called by the Tamino Server when an XML document
is to be retrieved from the Tamino Server. The map-out function is called for
the part of the document where the associated schema storage type is set to
"Map XTension" and the
onCompose property is defined.
A map-out function has three or four parameters, whose data types are as follows:
| Position / Direction | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 / in | Object ID | xs:int | sxdint | int |
| 2 / in | Element ID | xs:int | sxdint | int |
| 3 / out | XML Object | ino:XML-OBJ | sxdstring * | StringBuffer |
| 4 (optional) / in/out | Node Info | xs:string | sxdstring * | StringBuffer |
The Object ID and the Element
ID are used to uniquely identify the data to be retrieved by the
server extension function.
The XML Object represents the (part of the)
document to be retrieved and must contain the string representation of an XML
document or its parts that are valid against the schema used. The passed string
must be either the valid string representation of a node set or a character
string of printable characters containing neither
"<" nor ">".
The optional fourth parameter contains the node information that was passed to the Tamino Server by a previously called map-in function. As an in-out parameter it may be changed by the map-out function. If the previously called map-in function did not pass any node information, this parameter is an empty string (of length zero). The fourth parameter is optional. However, if the function does not support this parameter, there is no way in which node information can be accessed.
A map-out function can be used to retrieve those parts of an XML document stored outside of the Tamino database by a previous map-in function.
The map-out function is executed only if the corresponding sub-node was previously inserted. Consequently, no optional sub-nodes can be newly generated by means of map-out functions. The map-out output is validated against the schema definition. The document composition may fail if the validation fails.
See the section Tamino Server Extension Examples for information about programming examples.
Map-delete functions are called by the Tamino Server when an XML
document is to be deleted from the Tamino database. The map-delete function is
called for the part of the document where the associated schema storage type is
set to "Map XTension" and the
onDelete property is defined.
A map-delete function has two or three parameters, whose data types are as follows:
| Position / Direction | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 / in | Object ID | xs:int | in | int |
| 2 / in | Element ID | xs:int | in | int |
| 3 (optional) / in | Node Info | xs:string | in | String |
The Object ID and the Element
ID are used to uniquely identify the data to be deleted.
The optional third parameter contains the additional node information that had previously been passed from the map-in or map-out function to the Tamino Server.
Map-delete functions can be used to delete those parts of an XML document stored outside of the Tamino database by a previous map-in function.
See the section Tamino Server Extension Examples for information about programming examples.
The delete function is executed only if the corresponding sub-node was previously inserted.
See the section Tamino Server Extension Examples for information about programming examples.
As Tamino server extension objects are created implicitly by the Tamino Server, it is not possible to use constructors that pass parameters when an extension function is called. But it is often useful to initialize member variables with different values. If a server extension function – regardless of type – needs configuration information or the establishing of an initial environment, this can be achieved by executing an initial server extension function. Default values are associated with the parameters of initial functions when they are installed. These default values can be changed by the Tamino administrator using the Tamino Manager.
It is up to the Tamino server extension developer and the execution environment to decide which initialization should be performed, but mostly it will be used to set member variables, establish connections to external data-sources, etc. These initial settings remain valid unless modified by another server extension function until the session in which the server extension is executed ends. We recommend using server extension event functions to do the housekeeping for initialized actions if necessary.
The init function can have any number of input parameters, but no output or return parameter. The data types of the parameters are as follows:
| XML Type | Direct/C++ | Java |
|---|---|---|
| xs:boolean | sxdbool | boolean |
| xs:string | sxdstring | string |
| xs:double | sxddouble | double |
| xs:float | sxdfloat | float |
| xs:int | sxdint | int |
| ino:XML-OBJ | sxdstring | string |
Each parameter definition must have an associated default value that matches the corresponding type definition, otherwise a runtime error may occur. The X-Tension development tools (X-Tension Builder, the X-Tension Object Analyzer and the X-Tension Administration) allow the definition of these default values but do not enforce them. The values also can be set after the installation of the server extension by using the server extension administration features of the Tamino Manager.
Each server extension can contain at most one init function, which is implicitly called immediately before the first execution of any of its query, mapping or trigger functions, but after the objects constructor, if any. Subsequently, no parameter value is passed from the calling Tamino context, but all values are taken by default as denoted during development, analysis or modification after installation. In case of an error the init function should throw an error, which is propagated as the result of the current Tamino Server request.
If a server extension function is called repeatedly within a command request, transaction or user session, the same instance of the server extension object is used (see the section Calling Tamino Server Extensions).
For complex programming, it is therefore necessary to be able to react to Tamino Server events such as commit or rollback, end of request or end of session, for example in order to undo modifications initiated by a function call when a rollback was performed. Server event functions serve this purpose.
Each server extension object can contain at most one server event function.
A server event function has two parameters, whose data types are as follows:
| Position / Direction | Meaning | XML Type | Direct | Java |
|---|---|---|---|---|
| 1 / in | State | xs:int | sxdint | int |
| 2 / return value | Return Code | xs:int | sxdint* | int |
The first parameter indicates the event that happened, as listed in the following table. The second parameter contains a return code. In general, the return code should be set to zero, indicating success.
The following table shows the Tamino Server events that can and should be handled by a server event function:
| Tamino Server Event | Value |
|---|---|
| XML_REQUEST_END | 0 |
| XML_COMMIT | 1 |
| XML_ROLLBACK | 2 |
| XML_CONNECTION_END | 3 |
| XML_SUB_COMMIT | 4 |
| XML_SUB_ROLLBACK | 5 |
These events are defined as enum types in the file sxdinc.h.
These events are defined as constants in the Java-based interface for server extensions, SXSJBase.
Generally, the Server event function of a server extension object is called if at least one server extension function of type trigger, mapping or query of this object was called at least once during the corresponding period. The same event can be forwarded to several server extensions. In detail:
XML_SUB_COMMIT / XML_SUB_ROLLBACK
These events only occur in user sessions. At the end of a command, they are reported to all server extension objects from which a function was called while processing the command. These commands can occur several times within a request (see the section Order of Execution of Commands in the X-Machine Programming documentation for related information). They are used in a user session like subtransactions.
XML_COMMIT / XML_SUB_ROLLBACK
These events occur in user sessions when the user sends a commit or rollback command to the Tamino Server. At the end of a transaction they are reported to all server extension objects from which an arbitrary function was called within the same transaction.
In anonymous sessions each command is treated as a transaction of its own and closed with auto-commit or auto-rollback. At the end of each command, an XML_COMMIT or XML_ROLLBACK is reported to all server extension objects from which an arbitrary function was called within the same command.
XML_REQUEST_END
This event is reported to all server extension objects from which an arbitrary function was called within the same request. (Only "usage" requests are considered. A user-issued commit or rollback, which from the Tamino Server's point of view is also a request, does not lead to the XML_REQUEST_END event; it only results in XML_COMMIT or XML_ROLLBACK. The same is true for a session's end.)
XML_CONNECTION_END
This event is reported to all server extension objects from which an arbitrary function was called during the corresponding session, i.e. to all server extension objects that were initialized in the context of this session.
Server event functions are restricted in functionality:
Notes:
See the section Tamino Server Extension Examples for information about programming examples.