TM1 Programming Environment

This manual describes all the functions and features of the TM1 API. It assumes you are familiar with the basic concepts of TM1.

The API is intended to give access to many of the features and functionality of the TM1 OLAP engine. The API is designed for use with Microsoft C, C++ and Microsoft Visual Basic. All the C functions are supported by Visual Basic. However, some of the string and array value handling functions have a special version for Visual Basic. You should use these functions if you are programming in Visual Basic.

For C and C++ applications, include the header file TM1API.H. For Visual Basic applications, include the file TM1API.BAS.

The API has been optimized for use in a networked environment. As a result, the conventions used vary markedly from those used in other Application Programming Interfaces you may be familiar with. For example, all values are passed as pointers or handles to value capsules that contain the actual data. Location of the TM1 API DLLs:

There are three dynamic link libraries that must be loaded before you can use the TM1 API:

• TM1LIB.dll
• TM1SIP.dll
• TM1API.dll

These libraries must be loaded in the order that they are shown here. It is the programmer's responsibility to assure they are loaded in the correct order. There are three ways to do this:

• If the TM1API application resides in the same directory as the three DLLs, the libraries will be correctly loaded at run time.
• If the PATH environment variable includes the /bin directory, the libraries will be correctly loaded.
• You can explicitly load these libraries from within your application. For example, in Visual Basic you can call the Windows system function LoadLibrary() to each of the DLLs. The LoadLibrary() function will have to be called three times: once for each library.

Setting a Path to the DLLs:

The following procedure assumes that you accepted the default settings during the installation, and that the TM1 API .dll files are in C:\Cognos\TM1\bin. Follow these steps to tell the compiler where to find the TM1 API .dll files.

Steps:

1. From the Task Bar choose Start, Settings, Control Panel.
2. Double-click the System icon.
3. Click on the Advanced tab in the System Properties window.
4. Click Environment Variables.
5. Click PATH in the User Variables list.
6. In the Value field, add the full name of the directory in which the TM1 API .dll files are located. The delimiter between paths is the semi-colon (;).
7. Click OK.

Note: The above procedure is accurate for Windows NT 4.0. Procedures for other Windows operating systems may vary slightly.

Supported Compilers:

The TM1 API supports the following compilers:

• Microsoft Visual C++ Release 4.0 and higher
• Microsoft Visual Basic Release 4.0 and higher

Servers:

TM1 servers control access to system and user databases. In TM1, a server is a logical object having no parent of its own. The server has children that include, but are not limited to, cubes and dimensions, blobs (Binary Large Objects), clients (users), connections, and processes.

Servers use control cubes to keep track of databases, clients (users), groups, connections and other information.

A TM1 network is comprised of multiple local and remote servers.

Local Servers:

A local server runs on a users workstation. The local servers Admin Host machine is the user's workstation. If no Admin Server is running on the local machine, the local server starts one on the user's workstation. To start a local server, execute TM1S.EXE without configuration information or call TM1SystemServerStart.
Other users cannot access the local server by connecting to the admin host on that workstation.

Remote Servers:

A remote server controls access to public data objects. It can run on any workstation, including a users own workstation.

For a user to access the public data objects on a server, the user must be logged in to that server and must have at least READ rights. There are as many potential connections to a public server as there are server ports.
Steps:

1. Set up a configuration file specifying information for a specific server.
2. Create a shortcut to TM1S.EXE and add a -Z switch specifying the location of the server configuration file, TM1S.CFG. A server can be started by anyone.