SXS Trace is a mechanism that enables you to obtain information from the interface between Tamino Server and server extension functions. In cases where a Tamino server extension behaves unexpectedly, this information may help to determine whether the problem lies in the server extension or the Tamino Server. Server extension developers can define their own traces to add specific information to the SXS Trace.

SXS Trace is activated and deactivated from the Tamino Manager.

The information written by SXS Trace can be accessed using standard XQuery or X-Query queries. All these queries are to be entered in the Query field of the Tamino Interactive Interface.

SXS Trace supports the following actions:

• Activating SXS Trace

• Deactivating SXS Trace

• Programming User-Defined Trace Information

• Viewing SXS Trace Information

• Deleting SXS Trace Information

---

Activating SXS Trace

SXS Trace is activated for a whole database. All server extension functions called from XML requests are traced.

SXS Trace should be deactivated whenever it is no longer needed. It is deactivated by default each time the Tamino Server is started, in order to prevent unintended tracing.

To activate SXS Trace

1. Start the Tamino Manager.

   Expand the Databases object.

   Start and expand the database containing the server extensions that you want to trace.

2. Select the Server Extensions object.

3. Choose Extension Settings.

   The X-Tension Settings page appears.

4. Mark the X-Tension Trace Switch. Confirm with OK.

Deactivating SXS Trace

No server extension function called from XML requests will be traced after deactivating SXS Trace. However, SXS Trace information that has been recorded remains.

To deactivate SXS Trace

1. Start the Tamino Manager.

   Expand the Databases object.

   Start and expand the database containing the server extensions that you no longer want to trace.

2. Select the Server Extensions object.

3. Choose Extension Settings.

   The X-Tension Settings page appears.

4. Remove the check mark for X-Tension Trace Switch. Confirm with OK.

Programming User-Defined Trace Information

Server extension developers can define their own information to be included in the SXS Trace by using the following function:

Java call

SXSTrace(String text);

SxsTrace(String text);

To activate and retrieve the SXS Trace information, see the sections Activating SXS Trace and Viewing SXS Trace Information.

Direct

SXSTrace (sxdstring text);

Viewing SXS Trace Information

As long as SXS Trace is activated, trace information is automatically written and stored in XML documents of the collection ino:SXS-Trace in the Tamino Server. Insertions into ino:SXS-Trace are committed immediately after each entry; they are not part of the current transaction.

The information comprises the function name, date and time, session ID, the parameter values when entering a server extension function and after the return of this function, the parameter values passed to and returned from a callback, and exceptions. Server extension developers can define their own information to be included in the SXS Trace. For details, see the section Programming User-Defined Trace Information.

Database administrators can use standard XQuery or X-Query queries on the collection ino:SXS-Trace in the XQuery or X-Query tab of the Tamino Interactive Interface to access the trace information.

The following examples show how special trace information can be retrieved in XPath format.

Start the Tamino Interactive Interface from the Tamino program group under the Windows Start menu. In the Database URL field, enter "http://localhost/tamino/your_database" and in the Collection field, enter "ino:SXS-Trace".

Then enter one of the following commands in the Query field and choose the Query button:

ino:SXS-Trace

Shows all trace information stored in Tamino.

ino:SXS-Trace[FunctionEnter/@Name="MySXF"]

Shows all trace information for the "MySXF" server extension function.

ino:SXS-Trace/FunctionEnter[@Name="MySXF"]

Shows all trace information about the call of the "MySXF" server extension function.

ino:SXS-Trace/FunctionReturn[@Name="MySXF"]/Parameter

Shows all trace information about the return parameters of the "MySXF" server extension function call.

ino:SXS-Trace[FunctionEnter/@Name="MySXF"]/CallbackEnter

Shows all trace information about all callbacks that were used in the "MySXF" server extension function.

ino:SXS-Trace[FunctionEnter/@Name="MySXF"]/Exception

Shows all trace information about an exception that resulted from a call of the "MySXF" server extension function.

Deleting SXS Trace Information

SXS Trace information in the collection ino:SXS-Trace must be deleted manually, using the Tamino Interactive Interface.

To delete the SXS Trace

1. Start the Tamino Interactive Interface from the Windows Start menu. In the Database URL field enter "http://localhost/tamino/your database" and in the Collection field enter "ino:SXS-Trace";

2. Choose the Delete tab and enter

   ino:SXS-Trace

   in the Delete Query field.

This deletes all the trace information from the collection ino:SXS-Trace. You can also delete information selectively from the collection ino:SXS-Trace by specifying appropriate X-Query queries in the Delete field of the Tamino Interactive Interface.