Allgemeine Beschreibung

Einführung

Mit Hilfe der API-Server (früher ActiveX-Server) von Infoniqa ONE 200 können Sie ONE 200 Objekte und Methoden in Ihrem Programm verwenden und eine nahtlose Integration erreichen. Die Funktions-Schnittstelle ermöglicht den Zugriff zu gewissen Programm-funktionen der ONE 200-Anwendungen durch OLE-Automation (Dual-Schnittstelle). Über die Funktionsschnittstelle besteht die Möglichkeit zur direkten Einbindung ganzer Objekte und Funktionen in eine Fremdapplikation. Die Programm-objekte werden dabei dynamisch verknüpft und verschiedenen Applikationen zur Verfügung gestellt, wobei alle Anwendungsprogramme auf die gleiche Objektverwaltung zugreifen. In dieser Dokumentation finden Sie die Installations-Anleitung, sowie die Beschreibung der Objekte und Methoden. Die Beispiele sind jeweils in VisualBasic.

Änderungen in den Methoden gegenüber der vorherigen Version sind farbig im Inhaltsverzeichnis gekennzeichnet. Für Details ist die Methodenbeschreibung anzuschauen. Das Kapitel „Übersicht aller ActiveX-Methoden“, welche zu diesem Zweck früher diente, wird nicht mehr weiter geführt.

In einer neuen Version des API-Servers kann es vorkommen, dass Methodennamen ändern, wenn zwingende Felder neu hinzugekommen sind. Ist dies der Fall, wird die Methode einen neuen Namen erhalten, mit einem neuen Index z.B. alt: WriteUmbuchung, neu: WriteUmbuchung2

Wie angegeben, wird eine Methode nur umbenannt, wenn es sich um einen pflichtigen Parameter handelt. Da jedoch die gleichen Set-Methoden beim schreiben und updaten verwendet werden, kann ein Defaultparameter das umbenennen der Methode zufolge haben. Dies wurde so gelöst, dass bei solchen Methoden der Defaultparameter mit NOT_SET gesetzt wird. Anhand dieses wird der richtige Defaultwert beim schreiben und NOT_UPD beim updaten verwendet.

Installation API-Server

Lieferumfang:

Die API-Server werden vom Installationsprogramm installiert.

Objektaufbau der Schnittstelle

Automation -/ COM - Schnittstelle

Um die Methoden der ActiveX-Server verwenden zu können sind zwei verschiedene Technologien vorhanden Automation- und COM.

Lizenzierung

Ab SBS V-6.0.0 sind alle ActiveX-Server lizenzpflichtig. Je nachdem ob ein ActiveX-Server lizenziert ist, wird wenn die Verbindung zur Datenbank erstellt eine Fehlermeldung bzw. Warnung ausgegeben. Die entsprechende Fehlernummer ist weiter unten in diesem Dokument ersichtlich.

Beispiel eines solchen Fehlertextes:
Ihre Lizenz ist abgelaufen. Es stehen nur die Methoden des Objekts AXFinanz zur Verfügung.

Ist dies der Fall, können nur die Methoden des Globalen Objekts des ActiveX-Servers erfolgreich aufgerufen werden. Das Globale Objekt ist das Objekt welches die Verbindung zur Datenbank beinhalten, also AXFinanz, AXAuftrag und AXPersonal.

Speziell ist noch das BSExt-Objekt des Finanz ActiveX-Servers. Diese Methoden stehen zur Verfügung wenn einer der ActiveX-Server lizenziert ist.

Auf Simultan 2005 wurde die Lizenzierung angepasst, so dass pro Parent-Objekt eine Lizenzoption benötigt wird.

Fehlerbehandlung

Eine Fehlermeldung des ActiveX Servers wird durch ein Fehlerobjekt der aufrufenden Applikation übermittelt. Im Fehlerobjekt ist die Fehlernummer und die Fehlerbeschreibungen enthalten. Die restlichen Eigenschaften der Fehlerobjekte sind in den ActiveX Fehlermeldungen ohne Bedeutung. Fehlernummer grösser - gleich 10 000 sind Warnungen. Andere Fehler sind fatal. Die Fehlerobjekte übermitteln Fehler aus folgenden drei Ebenen:

1. Eigentlicher ActiveX-Server (SBSXAS,SBSAUF,XPERS)

2. Business-Objekte (SIMBUS)

3. Datenbank und Treiber (SIMCORE, ODBC)

Beispiel VC:

Private Sub Command_Click()

On Error GoTo ErrorHandler
    Dim a As Variant
    Dim b As Single

    Call Buch.ReadBuchung(1)

    While s <> "EOF"
        s = Buch.GetBuchZeile
        if s="EOF" GoTo ixend
        m_str = m_str & Chr(13) & Chr(10) & s
    Wend

Exit Sub

ErrorHandler:
    ErrorMSG err
End Sub
Public Sub ErrorMSG(err As ErrObject)
    Dim b As Long
    Dim s As String
    b = err.Number And 65535
    If b <> 0 Then
        If b < 10000 Then
            MSG = "Error # " & str(err.Number) & " was generated by " _
                & err.Source & Chr(13) & err.Description _
                & " Unsere Fehlernummer" & str(b)
        Else
            MSG = "Warning # " & str(err.Number) & " was generated by " _
                & err.Source & Chr(13) & err.Description _
                & " Unsere Fehlernummer" & str(b)
            Resume Next
        End If
        MsgBox MSG
    End If
    err.Clear
End Sub

Beispiel c#:

try
{
    // Logindialog
    _AXFinanz.ConnectSBSdb(dsn, database, uid, pwd, language);

}
catch(COMException e)
{
    var apiErrorCode= eCode=err.ErrorCode & 65535;
    if(apiErrorCode<10000)
    {
        var error ="Error # " + err.ErrorCode.ToString() + 
                   " was generated by " + err.Source + "\r\n";
    }
    Else
    {
        var error ="Warning #  " + err.ErrorCode.ToString() +
                   " was generated by " + err.Source + "\r\n";
    }
}
 

Euro
Der ActiveX-Server wurde von uns erweitert und ist nun Euro-tauglich. Die erweiterte Funktionalität (beim schreiben einer Buchung) entspricht der Finanz-Applikation. So kann bei Fragen zu Euro das Handbuch der Finanzapplikation verwendet werden.
Wenn der Mandant auf Euro umgestellt wurde, und über Euro gerechnet wird, tritt ein weiteres Problem auf. Die Berechnung des Basisbetrags muss dabei in der richtigen Reihenfolge ausgeführt werden, da zweimal gerundet wird. Um den Basisbetrag zu berechnen ist dabei folgendes Vorgehen notwendig:

Als Hilfestellung stellen wir die Methode calcBebuBetrag zur Verfügung, mit dieser kann der Bebu-Betrag, der beim schreiben einer Buchung verwendet wird einfach berechnet werden. (siehe calcBebuBetrag).

Schnittstellenbeschreibung

In dieser Dokumentation ist jede Schnittstelle in einer Tabelle eingetragen, dabei sind neben der Position und des Typs noch weitere Informationen vorhanden.

Aus der unten stehenden Tabelle sind die genauen Bedeutungen ersichtlich.

Bemerkung:
Strings welche die Länge überschreiten werden in der Datenbank auf die maximal erlaubte Länge des konkreten Tabellenfeldes gekürzt.

Achtung

Um Buchungen oder Sammelbuchungen zu schreiben, sollte die Methode CalcBebuBetrag verwendet werden, denn diese Methode liefert zur angegebenen Währung, Kurs und Datum den richtigen Bebubetrag in Basiswährung, wobei auch die Rundung berücksichtigt wird.

Gerundet wird auf die Basiswährung des aktuellen Mandanten und zwar nur, wenn der Basisbetrag berechnet werden muss, d.h. ein Beleg in Fremdwährung geschrieben wird.

z.B.

Mandant ZZ, Basiswährung CHF, Rundung 0.01

Bebubetrag = xxx.CalcBebuBetrag(“DEM“, “85.00“, “ “, “100.14“) è Bebubetrag = 85.12

Bebubetrag = xxx.CalcBebuBetrag(“DEM“, “85.00“, “ “, “100.15“) è Bebubetrag = 85.13

Mandant ZZ, Basiswährung CHF, Rundung 0.05

Bebubetrag = xxx.CalcBebuBetrag(“DEM“, “85.00“, “ “, “100.14“) è Bebubetrag = 85.10

Bebubetrag = xxx.CalcBebuBetrag(“DEM“, “85.00“, “ “, “100.15“) è Bebubetrag = 85.15

Rundung

Alle Beträge die dem ActiveX-Server übergeben werden, werden auf 2 Stellen nach dem Komma gerundet und übergebene Kurse auf 6 Stellen nach dem Komma.

Gerundet wird nach mathematischen Regeln, d.h. ein übergebener Betrag wird nur einmal gerundet.

Runden auf 0.01 (2 Stellen nach dem Komma) heisst:

Von einem vorhandenen Betrag werden alle Stellen verwendet. Wenn nun auf 0.01 gerundet werden muss, wird kontrolliert, ob der Absolutbetrag (eine negative Zahl wird in eine positive Zahl umgewandelt) grösser gleich der Hälfte der Rundung ist. Ist dies der Fall wird aufgerundet.

Optimierung

Die Performance des ActiveX-Servers SBSxas.ocx wurde verbessert. Dies geschieht indem oft benötigte Daten, nur einmal eingelesen werden. Werden diese Daten erneut benötigt, wird nicht auf die Datenbank zugegriffen, sondern die vorher eingelesenen Daten werden verwendet.

Aus diesem Grund muss bei einer Änderung der Daten wie z.B. des Kontenplans, der Währung oder anderer der ActiveX-Server frisch initialisiert werden.

Gefahren

Automatische Berechnung des Bebubetrags

Beim schreiben von Belegen verlangt der ActiveX-Server SBSxas den Bebubetrag in Basiswährung. Als neues Feature kann anstelle des Betrags der String CALCULATE übergeben werden. Mit diesem String wird der zu verwendende Bebubetrag automatisch berechnet.

Hier ist jedoch die Gefahr vorhanden, dass Belege, welche zuvor abgewiesen wurden (Fehlermeldung 268 Bebubuchung ist nicht plausibel) nun alle erfolgreich geschrieben werden. Der Client ist nun selbst verantwortlich, dass seine Einstellungen und die Einstellungen in ONE 200 identisch sind, so z.B. das wenn ONE 200 auf Euro umgestellt wurde, der Client dies auch weis und die Daten (Kurs) richtig übergibt.

Der String CALCULATE darf dabei pro Eingabefeld nur einmal vorhanden sein, da sonst der Bebubetrag nicht eindeutig bestimmt werden kann.

Multithreading

Die APIs sind nicht Multithreading tauglich. D.h. ein API unterstützt nur eine Connection. Möchte man sich ein Multithreading taugliches System aufbauen, müssen verschiedene API-Objekten erzeugt und diese verwendet werden. Z.B. ein Applikationsserver auf dem Server der pro Client-Zugriff ein API-Objekt beinhaltet. Da die APIs eigentlich nicht für solche Funktionalitäten ausgelegt sind, muss noch überlegt werden, dass viele Daten gecached werden. Daraus folgt, dass für solche Funktionalitäten in einem Applikationsserver nur eine Instanz des AXFinanz-Objekts vorhanden sein darf und keines seiner Kinder-Objekte. Somit ist auch gewährleistet, dass die zugehörigen Kinder-Objekte keine gecachten Daten beinhalten (besser noch währe, wenn der Applikationsserver keine einzige Instanz des API speichert).

Werden via des AXiBSExt-Objekts Stored Proceduren ausgeführt, die Daten zurückliefern, muss beachtet werden, dass die Stored Procedure offen bleibt, bis die Funktion Fetch EOF zurückgibt oder das Objekt zerstört wird. In anderen Worten heisst dies, dass es sonst zu locking-Problemen auf dem SQL-Server kommen kann.

Durch den Aufbau unserer APIs ist das freigeben (Zerstören der Objekte) vordefiniert. Gemäss Dokumentation müssen alle Objekte in umgekehrter Reihenfolge der Allozierung Dealloziert werden. Der Grund darin liegt am Parent-Objekt (beim Finanz API ist dies AXFinanz). Dieses Parent Objekt erstellt die Verbindung zur Datenbank und gibt die Connection den Kindern weiter. D.h. wird z.B. das Parent-Objekt zuerst freigegeben, wird auch die Connection freigegeben und ist somit in allen Objekten nicht mehr gültig. Dies ist besonders in Visual Basic spürbar, denn dort stürzt die Entwicklungsumgebung ab, wenn man den Debug-Modus stoppt.

In allen anderen Entwicklungsumgebungen treten diese Problem nicht auf. So kann eine Applikation nach dem beenden immer noch im Taskmanager sichtbar sein, oder plötzlich komische Fehlermeldungen ausgeben (nicht genügend Speicher usw.).

Unterstützte Programmiersprachen

C#

Early Binding

using SBSXASLib;
SBSXASLib.AXFinanzClass earlyAXFinanz=new AXFinanzClass();
string version=earlyAXFinanz.GetVersion;
SBSXASLib.AXiBSExt earlyBsext=(SBSXASLib.AXiBSExt)earlyAXFinanz.GetBSExtensionObj;
earlyAXFinanz.ConnectSBSdb("LOKAL", "Sage200", "sage200admin", "", "2055", "");
 
//Objekt freigeben (umgekehrte Reihenfolge)
System.Runtime.InteropServices.Marshal.ReleaseComObject(earlyBsext);
System.Runtime.InteropServices.Marshal.ReleaseComObject(earlyAXFinanz);

Late Binding

Type tApp=Type.GetTypeFromProgID("SBSXas.AXFinanz");
object lateAXFinanz=Activator.CreateInstance(tApp);
 
object[] args=null;
args=new object[6];
args[0]="LOKAL";
args[1]="Sage200";
args[2]="sage200admin";
args[3]="";
args[4]="2055";
args[5]= "";

Der letzte Parameter der Methode ConnectSBSdb ist ein Defaultwert. Dieser wird verwendet wenn ein Objektarray erzeugt wird, der nur 5 Parameter beinhaltet.

lateAXFinanz.GetType().InvokeMember("ConnectSBSdb",
BindingFlags.Default | BindingFlags.InvokeMethod,
null, lateAXFinanz, args);
 
object oVersion=lateAXFinanz.GetType().InvokeMember("GetVersion",
BindingFlags.Default | BindingFlags.GetProperty,
null, lateAXFinanz, args);
 
object lateBSExt=lateAXFinanz.GetType().InvokeMember("GetBSExtensionObj",
BindingFlags.Default | BindingFlags.GetProperty,
null, lateAXFinanz, args);
 
args=new object[2];
args[0]="tp_getverwaltung";
args[1]="0{>}ZZ{>}";
 
lateBSExt.GetType().InvokeMember("Execute",
BindingFlags.Default | BindingFlags.GetProperty,
null, lateBSExt, args);
 
//Objekt freigeben (umgekehrte Reihenfolge)
System.Runtime.InteropServices.Marshal.ReleaseComObject(lateBSExt);
System.Runtime.InteropServices.Marshal.ReleaseComObject(lateAXFinanz);

C++\MFC

Mit Visual Studio 6.0 oder Visual Studio .Net 2003

Early Binding (ohne SmartPointers)

#include <atlbase.h>
#import "C:\programme\simultan\bin\sbsxas.ocx"
using namespace SBSXASLib;
_AFX_THREAD_STATE* pState = AfxGetThreadState();
if(pState->m_bNeedTerm==0)
AfxOleInit(); 
 
if (afxContextIsDLL)
OleInitialize(NULL);
 
 
//Instanz des AFFinanz Objekts erzeugen
SBSXASLib::IAXFinanzPtr m_pIAXFinanz;
bool ok=m_pIAXFinanz.CreateInstance( __uuidof(AXFinanz) );
 
CComBSTR dsn;
dsn="Lokal";
 
//Verbingung zur Datenbank erstellen
try
{
m_pIAXFinanz->ConnectSBSdb(_bstr_t(dsn), _bstr_t("Sage200"), _bstr_t("sage200admin"), _bstr_t("") ,_bstr_t(L""), _bstr_t(L""));
}
catch (_com_error & err)
{
 
}
 
//AXiBSExt Objekt erstellen
IDispatch* pIDispatch;
SBSXASLib::IAXiBSExtPtr m_pIAXiBSExt;
 
pIDispatch = NULL;
m_pIAXFinanz->get_GetBSExtensionObj(&pIDispatch);
m_pIAXiBSExt = NULL;
pIDispatch->QueryInterface(__uuidof(IAXiBSExt), (void**)&m_pIAXiBSExt);
 
//Referenzcount reduzieren, da das Objekt pIDispatch nicht mehr weiter verwendet wird.
//Ansonst wird der Destruktor auf m_pIAXiBSExt nicht ausgeführt bzw. am Ende des Programms
//was zu Abstürzen führt.
pIDispatch->Release();
 
CComBSTR  m_BSTRInit;
 
//Stored Procedure ausführen    
m_pIAXiBSExt->get_Execute(_bstr_t("tp_getland"), _bstr_t("{>}"),&m_BSTRInit);
m_pIAXiBSExt->get_Fetch(&m_BSTRInit);
CString tmp=m_BSTRInit;
 
//Objekt freigeben (umgekehrte Reihenfolge)
m_pIAXiBSExt->Release();
m_pIAXiBSExt.Detach();
 
m_pIAXFinanz->Release();
m_pIAXFinanz.Detach();

Early Binding (mit SmartPointers)

#include <atlbase.h>

#import "C:\programme\simultan\bin\sbsxas.ocx"

using namespace SBSXASLib;

_AFX_THREAD_STATE* pState = AfxGetThreadState();
if(pState->m_bNeedTerm==0)
AfxOleInit(); 
 
if (afxContextIsDLL)
OleInitialize(NULL);
 
IAXFinanzPtr m_pIAXFinanz;
m_pIAXFinanz.CreateInstance(__uuidof(AXFinanz));
IDispatch* pIDispatch;
m_pIAXFinanz->get_GetBSExtensionObj(&pIDispatch);
 
IAXiBSExtPtr m_pIAXiBSExt = pIDispatch; // ruft QueryInterface auf
if (pIDispatch) 
pIDispatch->Release();
 
//Objekt zerstören (umgekehrte Reihenfolge)
m_pIAXiBSExt->Release();
m_pIAXFinanz->Release();
 
m_pIAXiBSExt.Detach();
m_pIAXFinanz.Detach();

Late Binding

_AFX_THREAD_STATE* pState = AfxGetThreadState();
if(pState->m_bNeedTerm==0)
AfxOleInit(); 
 
if (afxContextIsDLL)
OleInitialize(NULL);
 
LPDISPATCH pDisp;
LPUNKNOWN pUnk=NULL;
CLSID clsid; 
 
//Instanz des AXFinanz Objekts erzeugen
 
IAXFinanz m_IAXFinanz;
 
::CLSIDFromProgID(L"SBSxas.AXFinanz", &clsid); // from registry
if(::GetActiveObject(clsid, NULL, &pUnk) == S_OK) {
VERIFY(pUnk->QueryInterface(IID_IDispatch,
(void**) &pDisp) == S_OK);
m_IAXFinanz.AttachDispatch(pDisp);
pUnk->Release();
}
else 
{
if(!m_IAXFinanz.CreateDispatch("SBSxas.AXFinanz"))
{
AfxMessageBox("SBSxas.AXFianz not found");
AfxThrowNotSupportedException();
}
}
 
m_IAXFinanz.ConnectSBSdb("LOKAL", "Sage200", "sage200admin", "", "2055", "");
 
IAXiBSExt m_IAXiBSExt(m_IAXFinanz.GetGetBSExtensionObj());
m_IAXiBSExt.GetExecute("tp_getverwaltung", "0{>}ZZ{>}");
 
//Objekt freigeben (umgekehrte Reihenfolge)
m_IAXiBSExt.ReleaseDispatch();
m_IAXiBSExt.DetachDispatch();
 
m_IAXFinanz.ReleaseDispatch();
m_IAXFinanz.DetachDispatch();

Visual Basic

Early Binding

Dim oFinanz As SBSXASLib.AXFinanz
Set oFinanz = New SBSXASLib.AXFinanz
Set oBsExt = oFinanz.GetBSExtensionObj
Call oFinanz.ConnectSBSdb(dsn, dbName, uid, pwd, locale, Applikationsname)
Call oBsExt.Execute(StorProcName, inputParList)
 
//Objekt freigeben (umgekehrte Reihenfolge)
Set oBsExt=Nothing
Set oFinanz=Nothing

Late Binding

Dim oAXFinanz As Object
Set oAXFinanz = CreateObject("SBSXAS.AXFinanz")
Set oBsExt = oFinanz.GetBSExtensionObj
Call oFinanz.ConnectSBSdb(dsn, dbName, uid, pwd, locale, Applikationsname)
Call oBsExt.Execute(StorProcName, inputParList)
 
//Objekt freigeben (umgekehrte Reihenfolge)
Set oBsExt=Nothing
Set oFinanz=Nothing