Tamino Server Extension Functions

The information in this document is broken down as follows:


Server Extension Objects

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. More details can be found in the section Developing Tamino Server Extensions.

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.

Types of Server Extension Functions

Tamino X-Tension supports the following server extension function types according to the context of execution:

  • Query Functions

    that are explicitly called from within X-Query queries;

  • Trigger Functions

    that are used for executing functions when storing or deleting a related document independent of mapping;

  • Shadow Functions

    that are used to create index values for non-XML documents as a shadow of the original;

  • Mapping Functions

    that are used for storing, retrieving, or deleting documents and called by Tamino document processing, composing or on delete;

  • Initial Functions

    that allow initializing functions to be executed on the server extension object prior to any query, trigger or mapping function execution;

  • Server Event Functions

    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.

Function Naming

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

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:

Query Function Parameters and Data Types

A query function has zero or more "in" parameters and exactly one return value.

Direct and Java

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

Passing Parameters

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

Query Function Call Syntax

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:

  1. String constants in server extension query functions must be enclosed in single or double quotation marks, otherwise they are interpreted as XPath expressions.
  2. A string containing double quotation marks must be enclosed in single quotation marks; for example: query ('ino:name="sample"').

Conversion of Query Function Parameters

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 in X-Query/XQuery

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:

Query Functions at Root Level

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.

Query Functions in Filters

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.

Trigger Functions

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.

Execution

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 (as described in the section Exceptions) 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.

Insert Trigger

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.

Execution

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.

Update Trigger

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.

Execution

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.

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

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

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

  4. 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 Trigger

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.

Execution

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.

Shadow Functions

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.

Signature for onTextInsert Functions

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

Signature for onBinaryInsert Functions

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.

Mapping Functions

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.

Execution

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

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.

Considerations for key building:

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.

Execution

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

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.

Execution

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

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.

Execution

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.

Initial Server Extension Functions

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.

Execution

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.

Server Event Functions

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

Direct

These events are defined as enum types in the file sxdinc.h.

Java

These events are defined as constants in the Java-based interface for server extensions, SXSJBase.

Execution

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:

  1. Server event functions can only call system callback or HTTP callback functions.
  2. As Server event functions are processed after termination of the XML request which makes the server extension function calls, they cannot call callbacks implying database operations. Therefore XML callbacks and ODBC callbacks cannot be used within Server event functions. If an XML callback is used in a Server event function, a runtime error occurs. If an ODBC callback is used, an error message is output.
  3. Exceptions should not be thrown in Server event functions. They are caught, but have no effect.

See the section Tamino Server Extension Examples for information about programming examples.