An installed Tamino API for C delivers the following directory structure:

<TaminoInstallDir>
       |
       --- SDK
            |
            --- TaminoAPI4C
                      |
                      --- Documentation
                      --- include
                      --- lib
                      --- examples

• Documentation
  This directory contains the API's documentation in HTML and PDF.

• include
  This directory contains the header file TaminoAPI4C.h and TaminoAPI4C_2.h, which lists predefined constants and the function prototypes.

• lib
  This directory contains the platform-dependent shared libraries, e.g. TaminoAPI4C.lib and TaminoAPI4C.dll for Windows platforms, and libTaminoAPI4C.so for some UNIX platforms.

• examples
  This directory contains some examples on how to use the Tamino API for C.

This document provides detailed information on how to use the API in a C language context. If you want to call the functions provided by the Tamino API for C from another programming language, consult the language reference documentation for information about calling external C functions contained in shared libraries.

The following topics are covered below:

• Writing and Compiling an Application

• Linking an Application

• Running an Application

---

Writing and Compiling an Application

An application written in C that uses the Tamino API for C should follow the ANSI C specifications and include the provided header file TaminoAPI4C.h to obtain the function prototypes of the API.

The API is initialized by a call to tac_init(), which takes a database name as its argument. The corresponding server on which the database resides is found through eXtended Transport Services (XTS), a Software AG product delivered with Tamino XML Server. XTS either consults the local computer or a predefined server to obtain this information. If initialization is successful , tac_init() returns a non-negative handle. This handle is used as the first argument to all subsequent API calls, up to a final tac_end() call which finalizes the API.

Each handle can only be used by one thread. In a multi-threading environment, each thread must issue its own tac_init() command in order to obtain its own handle that must be kept track of by the programmer. Between the tac_init() call and the corresponding tac_end() call, different operations can be performed on the database, for example, inserting and deleting XML and non-XML documents. For more details, see the section Examples or Requests using X-Machine Commands. When working in a session context by issuing a tac_connect() command, the session ID and the session key are automatically kept track of in the Tamino API for C until the corresponding tac_disconnect() call is submitted.

Linking an Application

Tthe shared library lib64/libTaminoAPI4C.so must be known to the linker. The file can be found in the lib/ directory of the API distribution. This shared library needs some libraries that are distributed with the Tamino XML Server CD, most notably the WSL (webserverless API) and XTS (eXtended Transport Services) libraries. Additionally the directory $INODIR/$INOVERS/sagcom64/ must be known to the linker.

Running an Application

An application that uses the Tamino API for C must know the path to the provided shared library. This can be achieved by setting the PATH variable (Windows) or the LD_LIBRARY_PATH variable (UNIX) to the directory that contains the library, e.g. <TaminoInstallDir>/SDK/TaminoAPI4C/lib (UNIX) following the directory structure given above. The Tamino API for C shared library needs some libraries that are distributed with the Tamino XML Server CD. See the previous section Linking an Application. These directories must also be included in the library path.