API Tutorial (not .net)

At the start of a TM1 API project a few steps are necessary to get connected,

1.      Include the TM1 API Module

2.      At the Beginning of the Project use the ChDir and ChDrive function and set the Selected Directory to the Directory that contains TM1api.dll or put the bin dll files in the projects folder.

                example:

                   ChDir “C:Program FilesApplixbin”

                   ChDrive “C”

The Best way to get the Correct Path is By Accessing the Registry at Path:

    SoftwareApplixInstall9.0

    Key: InstallDir

It Pays to create Module Global Values to accommodate the TM1 Value Necessities (hUser, pGeneral)

and Before calling any TM1 Function use the TM1SystemOpen and TM1ValPoolCreate.

  hUser = TM1SystemOpen()
pGeneral = TM1ValPoolCreate(hUser)

The following outlines the process that will connect a user handle to a local TM1 Server

A Custom function at the Beginning of the code called GetTM1Directory changes the Windows Active directory to the TM1 Bin Directory and is a Vital Step see TM1 API Programming – Initial Steps Blog

This Function will return the hUser Capsule (long) if the Credentials are Correct

Note: pGeneral and hUser are Global Variables in another Module

Function ConnectToServer(ByVal sServer As String, ByVal sUsername As String, ByVal sPassword As String) As Long
Call GetTM1Directory

‘Values
Dim iType As Long

‘TM1 Values
Dim vServer As Long
Dim vUser As Long, vPassword As Long

‘Code start
hUser = TM1SystemOpen()
pGeneral = TM1ValPoolCreate(hUser)

vServer = TM1ValString(pGeneral, sServer, Len(sServer))
vUser = TM1ValString(pGeneral, sUsername, Len(sUsername))

    ‘If the password is nothing we still need to send 1 as the lenght to the ValString Function
If sPassword = “” Then vPassword = TM1ValString(pGeneral, “”, 1)
If sPassword <> “” Then vPassword = TM1ValString(pGeneral, sPassword, Len(sPassword))

hServer = TM1SystemServerConnect(pGeneral, vServer, vUser, vPassword)

      iType = TM1ValType(hUser, hServer)
Select Case iType
Case TM1ValTypeObject
ConnectToServer = hUser
Case TM1ValTypeError

          ‘User Login is Invalid
TM1SystemClose (hUser)
End Select

End Function

This code will retrieve the Perspectives hUser Value, Please note that you will still have to Create the pGeneral (General Pool) to Continue API Programming.

hUser = TM1_API2HAN
voDatabase = TM1SystemServerHandle(hUser, << Server Name >>)

******** TM1_API2HAN = hUser ********

Declare Function TM1_API2HAN Lib “tm1.xll” () As Long
Declare Sub TM1SystemServerClientName_VB Lib “tm1api.dll” (ByVal hUser As Long, ByVal index As Long, ByVal res As String, ByVal max As Integer)
Declare Function TM1ValPoolCreate Lib “tm1api.dll” (ByVal hUser As Long) As Long

Function GetTM1pUsername() As String
Dim hUser As Long, pGeneral As Long
Dim sRes As String * 100
sRes = “”

hUser = TM1_API2HAN
pGeneral = TM1ValPoolCreate(hUser)

TM1SystemServerClientName_VB hUser, 1, sRes, 100

GetTM1pUsername = Trim(sRes)
End Function