Tamino XML Server Version 9.7
 —  Tamino XML Schema User Guide  —

Tamino-Specific Extensions to the Physical Schema

The physical schema specifies physical storage information, for example for mapping and indexing.

This section describes the Tamino-specific extensions to the physical schema under the following headings:


Doctype Specific Extensions

The following topics are covered in this section:

Structure Index

This element specifies whether a structure index is created for the corresponding doctype. The element is of type xs:NMTOKEN. The tsd:structureIndex element can have one of the following values:

none

No structural indexing is done.

condensed

The repository registers the existence of an undeclared node for the doctype.

full

The repository registers both the existence of undeclared nodes and the instances in which they occur.

The default value is condensed.

Computed Indexes

Computed indexes defined for a doctype allow for user-defined indexing based on an indexing function defined in an XQuery module. For details refer to the section Advanced Indexes in the Performance Guide.

Definition of Unique Keys

For a description of how to define unique keys, refer to the topic Definition of Unique Keys in the section Physical Schema for Elements and Attributes.

Compression

The tsd:compress element specifies compression options for the physical storage of the data. It specifies whether instances belonging to the corresponding doctype are physically stored in a compressed or an uncompressed format (the latter is recommended for small data records only). Also, the user can specify maximum compression or optimal performance. The tsd:compress element is of type xs:NMTOKEN.

Note:
This option is not applicable for non-XML data.

The following values are allowed:

smart

This is the default value. Tamino checks the data to be stored and uses the best compromise between speed and size.

always

Always compress as much as possible. This choice is appropriate if you are primarily interested in reducing storage size. Especially for small documents, this minimizes disk space but increases retrieval time.

none

Do not compress small data records. Large documents are not affected by this setting. This setting is recommended if you expect most of your documents to be small (< 8000 characters) and you want to optimize processing speed, at the price of increased storage space.

off

Do no compression at all.

utf8

Each character is replaced by its UTF-8 representation. This can result in a compression factor of up to 4, depending on platform and data.

Built-In Indexing of Non-XML Data

Indexing of non-XML data is possible, but in a somewhat different manner than the indexing of XML data. The following example shows how to define a non-XML index using the tsd:nonXML element:

<?xml version = "1.0" encoding = "UTF-8"?>
<xs:schema 
 xmlns:xs = "http://www.w3.org/2001/XMLSchema"
 xmlns:tsd = "http://namespaces.softwareag.com/tamino/TaminoSchemaDefinition">
  <xs:annotation>
    <xs:appinfo>
      <tsd:schemaInfo name = "nonXML">
        <tsd:collection name = "Hospital"></tsd:collection>
        <tsd:doctype name = "X-Rays">
          <tsd:nonXML>
            <tsd:index>
              <tsd:text></tsd:text>
            </tsd:index>
          </tsd:nonXML>
        </tsd:doctype>
      </tsd:schemaInfo>
    </xs:appinfo>
  </xs:annotation>
  .
  .
  .
</xs:schema>

A plain text index is created for non-XML character data.

Top of page

Physical Schema for Elements and Attributes

This section deals with the following topics:

The figures in The Schema Header show those parts of the metaschema describing information that can be associated with elements and attributes via xs:annotation and xs:appinfo using tsd:elementInfo and tsd:attributeInfo, respectively:

The meaning and usage of these extension elements and attributes are explained in detail in the Tamino XML Schema Reference Guide. A general explanation of the tsd:elementInfo/tsd:attributeInfo subtree follows.

Attaching Physical Schema Information to Specific Nodes

tsd:which

The tsd:which element enables you to specify different physical schema information represented by different tsd:physical elements inside a single tsd:elementInfo or tsd:attributeInfo (i.e. an element or attribute), if a node can be reached via multiple paths because of references to global elements or attributes. Physical schemas for different absolute path expressions can be grouped together. Therefore, if necessary, multiple tsd:which elements are allowed in one tsd:physical element to specify different possible access paths. If no tsd:which element is specified within a tsd:physical element, all possible paths not explicitly given in any tsd:which within a sibling tsd:physical have the same physical schema information.

The tsd:which element contains a string of type xs:string that describes an XPath expression, which must match the following constraints:

The following rules apply for the default behavior of the tsd:which element:

One situation where the usage of the tsd:which element is very advantageous is multi-path indexing. You can find an explained example including usage of the tsd:which element here.

context

The context attribute is used in tsd:elementInfo or tsd:attributeInfo elements specified within tsd:schemaInfo. Similar to tsd:which, its value is a path that determines the xs:element or xs:attribute node to which the tsd:elementInfo or tsd:attributeInfo element belongs.

Definition of Unique Keys

Starting with version 4.2, Tamino allows you to specify a uniqueness constraint at the doctype level. This means that you can indicate, during schema definition, fields or combinations of fields that Tamino should monitor, ensuring that they have a unique value within their doctype. The necessary checks are performed automatically when data are inserted and updated (or update-defined). An error message is issued if an attempt is made to violate a uniqueness constraint.

Unique keys are defined centrally in tsd:schemaInfo/tsd:doctype/tsd:logical. Below tsd:logical, you can define tsd:unique elements having one or more tsd:field children. These tsd:field children allow you to specify how the uniqueness constraint is composed of one or more fields. Each tsd:field child element has an attribute xpath of type xs:string.

Note:
The path is relative to the root element.

Caution:
If there are multiple tsd:field child elements of a given tsd:unique element, each child's xpath attribute must be distinct.

graphics/unique.png

Based on that, the following schema fragment shows how to define two unique keys for the structure displayed in the diagram:

<tsd:doctype name="A">
  .
  .
  .
  <tsd:unique name="CB-key">
    <tsd:field xpath="C" />
    <tsd:field xpath="B/@b" />
  </tsd:unique>
  <tsd:unique name="D-key">
    <tsd:field xpath="D" />
  </tsd:unique>
  .
  .
  .
</tsd:doctype>

In the example, two uniqueness constraints are defined: one for the combined key comprising the element C and the attribute b of element B; and the other one for element D.

Note:
You can define an arbitrary number of tsd:unique elements below the tsd:logical element.

The names of the fields to which the uniqueness constraint applies are specified using the xpath attribute of the tsd:field element. This attribute is mandatory. It is of type xs:string, with the additional requirement that its value must be a valid XPath expression, i.e. it must comply with the XML Path Language (XPath) Version 1.0 specification published by the W3C.

Valid xpath attributes are:

The following rules apply for unique key definitions:

For more information about how to achieve the best performance when using the unique key feature, see the Performance Guide.

Indexing XML Data for Native Storage

This section discusses some aspects of the various kinds of indices that Tamino offers and of indexing in XML databases in general. In detail, the following topics are discussed here:

Why Define an Index?

One of the most important reasons for defining a schema for XML data is to index the data for "native"storage, i.e. storing the data in Tamino's internal XML store, although a schema may also be needed for validation and extension purposes.

The performance of database systems depends largely on correct indexing. This is just as true for Tamino as it is for other database systems. Correct indexing is very important, as it is a prerequisite for efficient database processing and retrieval.

However, if you have data for native storage for which no index is required, it is not necessary to make any descriptions, declarations or specifications at all, as native is the default storage option for XML data in Tamino, and no indexing is also the default.

What is an Index?

In general, an index is a look-up table for reducing the time taken to query data stored in a database. The look-up table usually stores the corresponding record number for each occurrence of a given value in a database field. It is possible to define an index:

Example

For example, assume a document with the structure displayed in the picture below: a root element A has multiple children B, each having two children named C and D. Also assume that there are two instances of this document with the ino:id values 17 and 31 containing the names given in the lowest row of the picture.

graphics/index-tree.gif

Then the index look-up table for A/B/C based on these instances would look like this:

Index for A/B/C
John 17, 31
Mike 31
Paul 17

Similarly, the look-up table for an index for A/B/D would look like the following:

Index for A/B/D
Fuller 31
Miller 17
Smith 17, 31

However, Tamino does not use record numbers; rather, it uses the ino:id to identify data within the database.

Tamino also offers more complex types of indices: see the following sections.

Index Categories Supported by Tamino

There are two ways of classifying indices in Tamino:

Note:
For non-XML data, it is also possible to define text indices. This option is described in the section Built-In Indexing of Non-XML Data.

For more information about achieving the best performance when using these advanced indices, see the appropriate section of the Performance Guide.

How to Define an Index in Tamino

This can be accomplished either with help from a tool or manually. These options are described in the following sections:

Defining an Index Using Tamino Schema Editor

Using the Tamino Schema Editor documentation, it is easy to define an index:

Start of instruction setTo define an index using the Tamino Schema Editor

  1. Choose the element or attribute that is to be indexed in the tree-display on the left side of the Tamino Schema Editor.

    On the right side of the Tamino Schema Editor, two areas labeled with:

    will appear.

  2. In the Physical properties area, set the value for the property <index> to "standard" if you intend to define a standard index, or to "text" if you intend to define a text index.

    Instances of the chosen element or attribute will be indexed to optimize queries containing relations like comparisons in retrieval expressions.

    Note:
    There is also a "standard+text" option available if you want to define both standard and text indices synchronously.

For more information, see the documentation of the Tamino Schema Editor.

Defining an Index Manually

Start of instruction setTo define an index manually

To define advanced types of indices manually, add child elements to tsd:index that contain the appropriate information.

Simple text and standard Indices

Simple Indexing
Index Definition Using the tsd:index Element

The tsd:index element may contain:

A tsd:text element

This indicates that the node is indexed for full text retrieval.

A tsd:standard element

A standard index is built. This option is usually applied for data typing.

Neither

No indexing is performed.

A text index and a standard index may also be defined synchronously. In a simple index, neither the only tsd:text element nor the only tsd:standard element may have any child element.

XML Indexing Considerations

The challenge in indexing XML data lies in deciding which XML data you wish to store and what the important queries against the stored data are likely to be. Since the "meat" of the data often lies in terminal nodes or sub-trees, the guiding principle is therefore to define an access path, i.e. an index, to those terminal nodes that are likely to be queried. Subtrees that are not relevant for filter conditions do not need to be indexed.

Tamino provides default settings for attributes that allow you to generate a Tamino schema without any editing. By default, neither elements nor attributes are indexed. Thus, for a natively-stored node without index nothing at all needs to be specified. Furthermore, it is very simple to add indexing to a natively-stored node:

Start of instruction setTo create an index for a natively-stored node

A special case of defining schemas for XML data is the representation of recursive structures in a schema.

The practical management of indexing is explained in the section Examples.

The Reference Index: Indexing with Respect to Sub-Trees of a Document

The General Concept of the Reference Index

A simple index indicates that a node belongs to a certain document, but it does not contain any more precise information. This may lead to poor performance if the document contains similar or equal sub-trees occurring with multiplicity that would have to be searched. Tamino provides reference indexing so that you can tune your schema for better performance in these situations.

Reference indices provide improved support for very large documents and for high-complexity documents.

We speak of high complexity if sub-trees with multiplicity occur in the schema. The complexity is even greater if recursive structures occur in the schema.

The general idea behind reference definitions and reference index definitions is to keep an additional index containing only references for a predefined partial tree of the document and to identify these references for later use.

For example, if /Doc/A/B is specified as the reference node for the reference index within the contents of the tsd:refers element, B nodes will be registered in the reference index.

In more detail, this leads to the following consequences:

Example of a Reference Index

Again, assume a document with the structure displayed in the picture below: a root element A has multiple children B, each having two children named C and D. Also assume there are two instances with the ino:id values 17 and 31 containing the names given in the lowest row of the picture.

graphics/index-ref-tree.gif

We now introduce reference numbers to identify the B nodes that appear with multiplicity; we also replace the ino:ids in the right column of the traditional index look-up table by the reference numbers of the B nodes that appear with multiplicity.

The look-up table for an index for A/B/C based on these instances looks like this:

Reference Index for A/B/C:
John 7,9
Mike 10
Paul 8

Similarly, the look-up table for a reference index for A/B/D looks like the following:

Reference Index for A/B/D:
Fuller 9
Miller 8
Smith 7,10
Conclusion

The tsd:refers element of TSD can be used in two different ways, depending on the intention:

Reference Definition

You can define a reference based on either a standard index or a text index.

To define a standard index or a text index that references a particular path, add a tsd:refers element as a child element of the respective tsd:standard or tsd:text element. The content of this tsd:refers element is the path to the node that is to be used as a base for a reference. (This node is marked as a reference node.) It is given there as an absolute path according to the rules of the W3C's XPath language.

This means that not the whole document tree is covered by the index, but only the sub-tree below that path (in the example below it is /A/B, for example).

...
<xs:element name = "C" type = "xs:string">
...
  <tsd:elementInfo>
    <tsd:physical>
      <tsd:which>
        /Doc/A/B/C
      </tsd:which>
      <tsd:native>
        <tsd:index>
          <tsd:text>
            <tsd:refers>
              /Doc/A/B
            <tsd:refers>
          </tsd:text>
        </tsd:index>
      </tsd:native>
    </tsd:physical>
  </tsd:elementInfo>
...
</xs:element>
...

The following rules apply:

As long as these conditions are fulfilled, recursive structures can be indexed.

Reference Index Definition

A node B to be referenced in indexing can be defined as follows:

...
<xs:element name = "B" maxOccurs = "unbounded">
  ...
  <tsd:elementInfo>
    <tsd:physical>
      <tsd:native>
        <tsd:index>
          <tsd:reference>
            <tsd:refers/>
          </tsd:reference>
        </tsd:index>
      </tsd:native>
    </tsd:physical>
  </tsd:elementInfo>
  ...
</xs:element>

If this node has a child element C that should have a reference index relative to B, this is accomplished as follows:

For more complex schemas and their corresponding documents, TSD's reference index definitions offer the possibility of two-stage modeling, e.g. /Doc/A/B refers to /Doc/A and /Doc/A refers to the document id.

For example, imagine an element named B that should have an ancestor named A and should be described by the following element definition schema fragment:

The element B is defined by this element definition from the schema fragment with a reference index definition that works in such a way that references pointing to node B should now point to its parent /Doc/A, for which a reference must have been defined.

Note:
This schema fragment sets up a reference chain from B over A to the document root. This reference chain can also be denoted as B->A->Doc.

Another motivation for using reference index definitions may come from the fact that recursive structures can also be indexed if the rules given below are not violated.

The following rules apply generally for reference index definitions:

The tsd:refers child element of the tsd:reference element behaves the same as it does in a reference definition as described above.

Reference index definitions can also be combined with other index definitions, for example multi-path indices and compound indices.

Constraints on Reference Indices

You can find a more detailed example below in the section Example 6: Defining a Reference Index. For example, the index definitions made there accelerate the processing of the following queries:

However, the following queries do not benefit from the definition of a reference index:

General Rules for Index Combination

The following rules concerning combination possibilities apply to reference indices:

Advantages and Disadvantages of Reference Indexing
Advantages
Disadvantages
Effect of Reference Index Definitions on Tamino Limits

The number of documents that can be stored in a Tamino database decreases significantly when reference indices are used, especially when multiple definitions of a reference index have been made in this doctype.

Effects on Performance

The correct choice of reference indices can have a significant effect on performance. This is discussed in more detail in the Performance Guide.

Multi-Path Indices

In contrast to previous versions of Tamino, where every index reflected an absolute XPath address, it is now possible to define an index in Tamino whose XPath address matches special criteria. This index is called a multipath index. The definition of multi-path indices is discussed here under the following headings:

Motivation

The reasons that lead to the introduction of multi-path indices are as follows:

The General Concept of Multi-Path Indexing

A multi-path index allows data from multiple paths to be collected in a single index.

Whereas in simple indexing each index reflects an absolute XPath address, this does not hold for a multi-path index.

A multi-path index is filled by the data of all nodes that match the various XPath conditions. This increases the performance for queries with wildcards significantly, as only the sum of all relevant entries is searched (and not all possible combinations, as in a simple index).

A multi-path index can be defined either as a text index or as a standard index, depending on which was specified as the parent element of the tsd:multiPath element in the schema.

It is also possible to combine multi-path indexing with any other kind of indexing within one node:

- Simple standard index;
- Simple text index;
- Compound index.

Practically, a multi-path index is defined as follows:

All nodes (this includes both element nodes and attribute nodes) that should contribute to the multi-path index are identified by a special label that is unique within the entire schema. This allows you to specify easily the values that should be assembled into each index.

In the schema definition for a multi-path index, this is simply expressed as an additional element tsd:multiPath which contains the common label to be used in the index definitions of all nodes that should be indexed. All nodes (i.e. elements and attributes) that have the same label in their index definition address the same index.

For example, as you can find in the contents of the tsd:multiPath element, the three labels MultiPathIndex0, MultiPathIndex2 and MultiPathIndex3 are used in the example below.

This approach offers the following solutions:

Example Schema Excerpts for Multi-Path Indexing

First we discuss a simple example, showing the use of multi-path indexing in a recursive situation.

Imagine, for example, an element title that may be addressed as a child element within a recursive schema. See the illustration below:

graphics/tsdmulti-path-rec.png

To create a multi-path index for the element title, add the following lines to its tsd:native element:

.
.
.
<tsd:index>
  <tsd:text>
    <tsd:multiPath>Title index<tsd:multiPath>
  </tsd:text>
</tsd:index>
.
.
.

This code creates a multi-path index named Title index that covers all possible access paths that lead to title by recursion. One single index covers all recursion levels.

Now let us have a look at a simple example for highly connected schemas.

Imagine, for example, an element title that can be addressed via multiple paths within a highly connected schema. See the illustration below:

graphics/tsdmultipath-ex-1.png

To create a multi-path index for title, simply add the same lines as in the preceding example to its tsd:native element:

.
.
.
<tsd:index>
  <tsd:text>
    <tsd:multiPath>Title index<tsd:multiPath>
  </tsd:text>
</tsd:index>
.
.
.

This code creates a multi-path index named Title index covering all access paths that lead to title. However, index generation does not depend on the path leading to title in this case.

The generated multi-path index accelerates queries such as:

Play [ .//Title ~= "King" ]

Finally, let us discuss a more complex example:

.
.
.
<!-- global Element Definition for Title -->
  <xs:element name = "Title" type = "xs:string"> 
    <xs:annotation>
      <xs:appinfo>
        <tsd:elementInfo>
          <tsd:physical>
            <!-- default which for global Element Definition Title -->
            <tsd:native>
              <tsd:index>
                <tsd:text>
                  <tsd:multiPath>MultiPathIndex0</tsd:>
                </tsd:text>
              </tsd:index>
            </tsd:native>
          </tsd:physical>
          .
          . 
          .
          <tsd:physical>
            <tsd:which>/Play/Act/Title</tsd:which>
            <tsd:native>
              <tsd:index>
                <tsd:text>
                  <tsd:multiPath>MultiPathIndex2</tsd:multiPath>
                </tsd:text>
              </tsd:index>
            </tsd:native>
          </tsd:physical>
          <tsd:physical>
            <tsd:which>/Play/Act/Scene/Title</tsd:which>
            <tsd:native>
              <tsd:index>
                <tsd:text>
                  <tsd:multiPath>MultiPathIndex3</tsd:multiPath>
                </tsd:text>
              </tsd:index>
            </tsd:native>
          </tsd:physical>
        </tsd:elementInfo>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>
  .
  .
  .
  <!-- local Element Definition for /Play/Prologue /Title -->
  <xs:element name = "Title" type = "xs:string">
    <xs:annotation>
      <xs:appinfo>
        <tsd:elementInfo>
          <tsd:physical>
            <tsd:native>
              <tsd:index>
                <tsd:text>
                  <tsd:multiPath>MultiPathIndex2</tsd:multiPath>
                </tsd:text>
              </tsd:index>
            </tsd:native>
          </tsd:physical>
        </tsd:elementInfo>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>
  .
  .
  .
  <!-- local Element Definition for /Play/Act/Abstract/Title -->
  <xs:element name = "Title" type = "xs:string">
    <xs:annotation>
      <xs:appinfo>
        <tsd:elementInfo>
          <tsd:physical>
            <tsd:native>
              <tsd:index>
                <tsd:text>
                  <tsd:multiPath>MultiPathIndex3</tsd:multiPath>
                </tsd:text>
              </tsd:index>
            </tsd:native>
          </tsd:physical>
        </tsd:elementInfo>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>
  .
  .
  .

This definition creates three multi-path indices that cover all Title nodes, namely:

This situation is depicted in the following graphic:

graphics/tsdmultipath1.png

You can find another example in the section Example 4: Defining of a Multipath Index. For example, the index definitions discussed there accelerate the processing of the following queries:

General Rules for Index Combination

The following rules concerning combination possibilities apply to multi-path indices:

Constraints and Limitations

The following constraints apply to the definition of multi-path indices:

Advantages and Disadvantages of the Use of Multi-Path Indexing
Advantages

The main advantage of multi-path indexing is easy indexing of recursive and highly-connected structures.

Disadvantages

The main disadvantage of multi-path indexing is that sort operations are not supported.

Compound Indices

This section discusses the following topics related to compound indices:

Motivation

In some queries, combined value conditions on inner nodes (i.e. nodes that are neither the root note nor leaf nodes) appear with a multiplicity of more than one. For example, /A[B[C="x" and D="y"]] represents such a query. Characteristic for this construct is:

In general, such queries perform poorly using simple indices. This is because the simple index delivers a superset of the final result, which must then be filtered in a subsequent processing step. The compound indices that are available in Tamino since version 4.2.1 are ideally suited to accelerate such queries.

Note:
Reference indices are also well suited in this situation. To decide whether to use compound indexing or reference indexing, read the sections about the advantages and disadvantages of each kind of indexing in this document.

General Concept

A compound index is somewhat different from the other kinds of index discussed here. A simple index, a reference index and a multi-path index (as discussed above) are each bound to one specific element or attribute. This not true for a compound index, which comprises two or more different components, called fields. The definition, however, takes place in the inner node (B), which is the parent of both elements in the condition (C and D in the example).

To define a compound index, add a tsd:field element as a child element directly below the tsd:standard element.

The tsd:field element must appear at least twice (with different xpath attributes) to define a valid compound index.

Note:
If the tsd:field element appears as a child element of the tsd:standard element, in order to define a valid compound index it must appear at least twice, since at least two fields are required to set up a compound index. The xpath attributes of at least two tsd:field elements belonging to the same tsd:standard element must be different.

You can use the xpath attribute of the tsd:field element to specify a path to an element or attribute contributing to the compound index.

Important:
The xpath attribute is required.

A tsd:field element with a corresponding xpath attribute must be defined for each XPath address to be included in the compound index. Each path is relative to the element in which it is defined.

Note:
The order of the tsd:field elements is significant; it determines the order in which the values contribute to the index entry.

Supported xpath attributes are:

Sequences of element names (optionally followed by a single attribute name), separated by slashes

Any XPath expression that uses only the axes "child" and "attribute".

A single dot

The special case of a single dot ".", which indicates that the index is to be created from the value of the element and of the values of its attributes.

Caution:
It is possible, although generally not desirable, to define a schema with multiple equivalent definitions of compound indices. In this case, redundant indices are created.

Example for a Compound Index

Assume a document with the structure displayed below with a root element A having multiple children B, each having two children named C and D. Also assume there are two instances with the ino:id values 17 and 31 containing the names given in the lowest row of the picture.

graphics/index-tree.gif

The look-up table for a compound index for B(C,D) based on these instances is as follows:

Compound Index for B(C, D)
John_Fuller 31
John_Smith 17
Mike_Smith 31
Paul_Miller 17
Example Schema Excerpt for Compound Indexing

Let A be the root element of a document. A has child elements B and C (there may also be others). B has an attribute named b.

The following example defines a compound index for the combination of attribute b of element B and the element C:

<xs:element ...>
  .
  .
  .
  <tsd:elementInfo>
    <tsd:physical>
      <tsd:native>
        <tsd:index>
          <tsd:standard>
            <tsd:field xpath="C"/>
            <tsd:field xpath="B/@b" />
          </tsd:standard>
          .
          .
          .
        </tsd:index>
      </tsd:native>
    </tsd:physical>
  </tsd:elementInfo>
</xs:element>

The compound index created by this schema definition contains an entry for each combination of C and B/@b occurring below the element in whose tsd:elementInfo it appears.

The performance of queries such as /A[@b="x" and C="y"] is improved by this compound index.

You can find a more detailed example in the section Example 3: Defining a Compound Index of this document. The index definitions discussed there improve the performance of the following queries:

General Rules for Index Combination

The following rules concerning combination possibilities apply to compound indices:

Constraints and Limitations

The following constraints apply for the definition of compound indices:

Advantages and Disadvantages of Compound Indexing
Advantages
Disadvantages

Other Sources of Information on Indexing

Top of page

External Mapping

To map parts of XML documents to externally stored data (Adabas, or using a Tamino Server Extension), use the tsd:map element.

An example showing a mapping for an element follows:

<xs:element>
 <xs:annotation>
  <xs:appinfo>
   <tsd:elementInfo>
    <tsd:physical>
     <tsd:map>
     .
     .
     .
     </tsd:map>
    </tsd:physical>
   </tsd:elementInfo>
  </xs:appinfo>
 </xs:annotation>
 .
 .
 .
</xs:element>

The tsd:map element may contain an optional tsd:ignoreUpdate child element. If present, Tamino does not pass the corresponding part of the XML document to the internal data storage or X-Node during processing.

This section covers the following topics:

Mapping to Adabas Files

The Tamino schema provides constructs that allow you to store data in an Adabas file and/or retrieve data from an Adabas file via the Tamino X-Node.

Mapping to Adabas is done on a file basis. In other words, you do not have to model the whole of an Adabas database using the Tamino schema language; you model only those files and fields that you wish to access using Tamino.

Mapping to an Adabas file is explained under the following headings:

Pure vs. Hybrid Adabas Mapping

There are two possible approaches for mapping to an Adabas file:

Data is handled in the following manner if a pure Adabas mapping is present:

The following conditions must be fulfilled in order to establish a pure Adabas mapping:

Plain URL Addressing

Normally, when a document is inserted using plain URL addressing (HTTP PUT), Tamino returns the ino:id of the new document in the HTTP header field X-INO-ID. For pure X-Node Adabas doctypes, there is no ino:id when inserting a document, and therefore the X-INO-ID field contains zero. Consequently, the pure X-Node Adabas documents cannot be read using plain URL addressing (HTTP GET), even if they were inserted through Tamino.

Elements and Attributes for Adabas Mapping

This section describes the attributes that are of particular relevance to Adabas mapping.

Adabas-Specific Elements and Attributes

tsd:subTreeAdabas element

This element provides the database ID and file number in its attributes dbid and fnr, with an optional password in the password attribute.

dbid attribute

The dbid attribute belongs to the tsd:subTreeAdabas element. Its value contains the database ID of the Adabas database.

fnr attribute

The fnr attribute belongs to the tsd:subTreeAdabas element. It represents the file number of the Adabas file.

password attribute

The optional password attribute belongs to the tsd:subTreeAdabas element. It contains the password of the Adabas file to be accessed. The password has up to 8 characters.

tsd:subTreeAdabasPE element

This element models a mapping to an Adabas periodic group via Tamino X-Node.

tsd:nodeAdabasField element

This element is used in conjunction with the elements tsd:subTreeAdabas and tsd:subTreeAdabasPE to specify the characteristics of the leaf nodes.

shortname attribute

The shortname attribute can be an attribute either of the tsd:subTreeAdabasPE element or of the tsd:nodeAdabasField element. This is the shortname (e.g. "AH") of the corresponding field in the Adabas file. It can also be used in conjunction with Adabas MU fields.

Note:
This is the case if a tsd:multiple child element is present inside tsd:nodeAdabasField.

format attribute

The format attribute belongs to the tsd:nodeAdabasField element. It describes the format of the corresponding field in the Adabas file.

The following table presents a list of the possible format attribute values and their meaning:

format Description/Meaning
A Alphanumeric
B Binary
F Fixed Point
G Floating Point
P Packed Decimal
U Unpacked Decimal

Also refer to the Adabas documentation.

Note:
The format attribute can be specified either for a tsd:nodeAdabasField element describing a mapping to a single Adabas field (that does not have a child element tsd:multiple) or for those describing a mapping to an Adabas MU field (multiple field) tsd:nodeAdabasField (that can have a child element tsd:multiple).

Example Schema for Adabas Mapping

This example uses the Employees file in the demo database delivered with the Windows installation of Adabas Version 3.2 to illustrate mapping to an Adabas file.

The following is the Natural view of the "Employees" database:

Note:
The lines of special interest are printed in italics.


T L DB Name                              F Leng  S D Remark
- - -- --------------------------------  - ----  - - ------------------------
  1 AA PERSONNEL-ID                      A    8    D
       HD=PERSONNEL/ID
G 1 AB FULL-NAME
  2 AC FIRST-NAME                        A   20  N
  2 AD MIDDLE-I                          A    1  N
  2 AD MIDDLE-NAME                       A   20  N
  2 AE NAME                              A   20    D
  1 AF MAR-STAT                          A    1  F
       HD=MARITAL/STATUS
  1 AG SEX                               A    1  F
       HD=S/E/X
  1 AH BIRTH                             N  6.0    D
       HD=DATE/OF/BIRTH
       EM=99/99/99
G 1 A1 FULL-ADDRESS
M 2 AI ADDRESS-LINE                      A   20  N
       HD=ADDRESS
*      OCCURRENCES 1-6
  2 AJ CITY                              A   20  N D
  2 AK ZIP                               A   10  N
       HD=POSTAL/ADDRESS
  2 AK POST-CODE                         A   10  N
       HD=POSTAL/ADDRESS
  2 AL COUNTRY                           A    3  N
G 1 A2 TELEPHONE
  2 AN AREA-CODE                         A    6  N
       HD=AREA/CODE
  2 AM PHONE                             A   15  N
       HD=TELEPHONE
.
.
.

The file ada_empl.tsd is provided in the Tamino distribution kit to illustrate the mapping to the Employee database. Note that not all fields are mapped, so instances containing nodes that are not mapped are rejected. The graphical representation of this schema as it appears in the Tamino Schema Editor is shown below. The properties view is reduced to the physical properties pane, which shows as an example the mapping of the zip element to the Adabas field AK:

ada_empl TSD3 in the Schema Editor

Note that such a schema could also be a subtree within a schema for another doctype.

This schema allows Adabas data to be retrieved using Tamino X-Query expressions, for example:

/employees/employee[name/surname~="A*"]

This returns all employees whose surnames start with the letter "A".

The following XML object is an instance of the above schema and can be loaded into the Adabas database and retrieved using Tamino:

<?xml version="1.0" encoding="ISO-8859-1"?>
 <employee personnelid="007">
  <name>
   <firstname>James</firstname>
   <surname>Bond</surname>
  </name>
  <sex>M</sex>
  <birth>340401</birth>
  <address>
   <zip>SW13JB</zip>
   <city>London</city>
  </address>
</employee>

Mapping to Server Extensions

Server Extensions allow you to extend Tamino's functionality by executing user-defined application logic (written in languages such as Java or C++) at specified points in the processing of an instance. Server Extensions can be associated with elements and attributes at any level in a Tamino schema. When an element or attribute is associated with a Server Extension, the element is said to be "mapped" to the Server Extension.

Server Extensions can be used, for example, to let external programs handle indexing, storing or retrieval of data in ways not provided as standard by Tamino.

Mapping to a Server Extension means transferring control to an external function offered by the Server Extension. One Server Extension may offer several functions. Control can be passed to a Server Extension function during parsing of an incoming instance or during composition of an XML object as the result of a query. The invocation context is specified by the name of the Server Extension-specific child elements on the node. The associated Server Extension function is specified as the element value.

Mapping to Server Extension functions is described in this section under the following headings:

Node Attributes for Mapping to Server Extensions

This section describes the Tamino schema extensions that are of particular relevance to mapping elements to Server Extensions.

Server Extension-Specific Elements and Attributes

There is one single parent element in TSD offering all the functionality needed to map Tamino Server Extensions in conjunction with its child elements, namely the tsd:xTension element.

TSD provides the following mappings for Server Extensions:

tsd:xTension

This element is the parent element of the elements tsd:onDelete and tsd:onProcess.

The syntax of the values of these child elements is:

SXSModule.SXSFunction
tsd:onProcess

Specifies the name of the SXS function that is to be executed when data is stored using Tamino (that is, when using the Tamino _process request). The SXS function is called after parsing the associated element.

tsd:onDelete

Specifies the name of the SXS function that is to be executed when the associated element is to be deleted (that is, when the Tamino _delete request is issued).

Example of Mapping to Server Extensions

The following example demonstrates the mapping to a Server Extension Function. A doctype "Mail" describes the structure of an e-mail message.

The effect of the Server Extension function is that instead of storing instances of the doctype (i.e., e-mail messages) in Tamino, they are routed to an e-mail tool, which transmits the messages to the recipient.

The TSD schema describing the "Mail" doctype with mapping to Server Extensions contains a tsd:onProcess element specifying the corresponding Server Extension function to be invoked when processing a document:

<?xml version = "1.0" encoding = "UTF-8"?>
<xs:schema xmlns:xs = "http://www.w3.org/2001/XMLSchema"
 xmlns:tsd = "http://namespaces.softwareag.com/tamino/TaminoSchemaDefinition">
  <xs:annotation>
    <xs:appinfo>
      <tsd:schemaInfo name = "SXS">
        <tsd:collection>MailSXS</tsd:collection>
        <tsd:doctype name = "Mail">
          <tsd:logical>
            <tsd:content>closed</tsd:content>
            <tsd:accessOptions>
              <tsd:insert></tsd:insert>
            </tsd:accessOptions>
          </tsd:logical>
        </tsd:doctype>
      </tsd:schemaInfo>
    </xs:appinfo>
  </xs:annotation>
  <xs:element name = "Mail">
    <xs:annotation>
      <xs:appinfo>
        <tsd:elementInfo>

        <!--- Beginning of mapping to Server Extension--->
          <tsd:physical>
            <tsd:map>
              <tsd:xTension>
                <tsd:onProcess>SXSMail.SendMail</tsd:onProcess>
              </tsd:xTension>
            </tsd:map>
          </tsd:physical>
        <!--- End of mapping to Server Extension--->
        </tsd:elementInfo>
      </xs:appinfo>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name = "Recipient" type = "xs:string"></xs:element>
        <xs:element name = "Subject" type = "xs:string"></xs:element>
        <xs:element name = "Body" type = "xs:string"></xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Notes:

  1. In this example, the Server Extension function is specified on the root node of the doctype, thus ensuring that the function is executed after parsing the whole instance. It could also be placed at a subordinate node of a document node.
  2. Mapping to a Server Extension function means that the corresponding subtree of the XML document is not stored in Tamino, but is processed by the map-in function (see Tamino Server Extension Functions) being invoked.

The following XML object is an instance of the doctype "Mail". Using the schema definition above, this instance is not stored in Tamino, but sent to the e-mail address in the Recipient element:

<Mail>
  <Recipient>world@planet.org</Recipient>
  <Subject>Global greeting</Subject>
  <Body>Hello World!</Body>
</Mail>

Top of page