Przykłady zastosowań

Import dokumentu z pliku .TXT

Jest to szczególnie istotne dla firm wprowadzających bardzo długie transakcje zakupu. Często wraz z towarem jego dostawca dostarcza dyskietkę ze specyfikacją dostawy. Korzystając np. z programu Microsoft Excel można napisać prosty program wczytujący taki plik tekstowy do arkusza, a następnie łączący się poprzez CDN XL API z systemem CDN XL i generujący odpowiedni dokument zakupu.

Wsadowy import transakcji

Firmy wielooddziałowe często importują poprzez łącza modemowe transakcje ze swoich oddziałów do centrali, gdzie mają one być następnie wprowadzone do bazy danych. Program importujący transakcje może za pośrednictwem CDN XL API połączyć się z systemem CDN XL i zapisywać w jego bazie danych zaimportowane z oddziałów dokumenty.

Przykładowe kody

Poniżej przedstawione zostały przykładowe kody wykorzystujące CDN XL API.

Dadanie ZS z jednym elementem (VBA)

Sub Dodaj_Zamowienie()

Dim Sesja As Long

Dim Wynik As Long

Dim Login As XLLoginInfo_12

Dim IDDokumentu As Long

Dim Naglowek As XLDokumentZamNagInfo_12

Dim Element As XLDokumentZamElemInfo_12

Dim Zamkniecie As XLZamkniecieDokumentuZamInfo_12

Sesja = 0

IDDokumentu = 0

With Login

.Wersja = 12

.programID = "TestXL"

.Baza = "CDNXL_Test"

.OpeIdent = "ADMIN"

.OpeHaslo = ""

End With

Wynik = XLlogin_12(Login, Sesja)

If Wynik <> 0 Then

MsgBox("Błąd logowania: " & Wynik)

End If

With Naglowek

.Wersja = 12

.Typ = 6

.Akronim = "Test"

End With

Wynik = XLNowyDokumentZam_12(Sesja, IDDokumentu, Naglowek)

If Wynik <> 0 Then

MsgBox("Błąd dodawania nagłówka: " & Wynik)

End If

With Element

.Wersja = 12

.Ilosc = 10

.CenaKatalogowa = 1

.Towar = "Test"

End With

Wynik = XLDodajPozycjeZam_12(IDDokumentu, Element)

If Wynik <> 0 Then

MsgBox("Błąd dodawania pozycji: " & Wynik)

End If

With Zamkniecie

.Wersja = 12

.TrybZamkniecia = 2

End With

Wynik = XLZamknijDokumentZam_12(IDDokumentu, Zamkniecie)

If Wynik <> 0 Then

MsgBox("Błąd zamykania nagłówka: " & Wynik)

End If

Wynik = XLlogout_12(Sesja)

If Wynik <> 0 Then

MsgBox("Błąd wylogowania: " & Wynik)

End If

End Sub

Przekształcenie ZS do FS (VBA)

Public Sesja As Long

Public IDDokumentu As Long

Public Wynik As Long

Public ElemInfo As XLDokumentElemInfo_12

Sub Zaloguj()

Dim Login As XLLoginInfo_12

Sesja = 0

Wynik = 0

With Login

.Wersja = 12

.ProgramId = "X:VBA"

.Baza = "CDN_XL_Test"

.OpeIdent = ""

.OpeHaslo = ""

End With

Wynik = XLLogin_12(Login, Sesja)

If Wynik <> 0 Then

Wynik = MsgBox("Błąd logowania: " & Wynik)

Exit Sub

End If

End Sub

Sub DodajNaglowek()

Dim NagInfo As XLDokumentNagInfo_12

Worksheets("Nagłówek ZS").Select

Wersja = 12

With NagInfo

.Wersja = 12

.Typ = 4

.ZamFirma = Range("b2").Value

.ZamNumer = Range("c2").Value

.ZamTyp = Range("a2").Value

End With

Wynik = 0

Wynik = XLNowyDokument_12(Sesja, IDDokumentu, NagInfo)

If Wynik <> 0 Then

Wynik = MsgBox("Błąd dodawania nagłówka: " & Wynik)

Exit Sub

End If

End Sub

Sub ZamknijNaglowek()

Dim ZamkniecieInfo As XLZamkniecieDokumentuInfo_12

ZamkniecieInfo.Wersja = 12

ZamkniecieInfo.Tryb = 0

Wynik = 0

Wynik = XLZamknijDokument_12(IDDokumentu, ZamkniecieInfo)

If Wynik <> 0 Then

Wynik = MsgBox("Błąd zamykania nagłówka: " & Wynik)

Exit Sub

Else

Wynik = MsgBox("Poprawnie dodano dokument WZ.")

End If

End Sub

Function Pierwszy_wolny_rekord() As Integer

Dim licznik As Long

licznik = 2

Do

If Range("A" & licznik).Value = "" Then

Pierwszy_wolny_rekord = licznik

Exit Function

Else

licznik = licznik + 1

End If

Loop

Stop

End Function

Sub DodajPozycje()

Worksheets("Pozycja ZS").Select

licznik = Pierwszy_wolny_rekord()

For x = 2 To licznik - 1

With ElemInfo

.Wersja = 12

.ZamFirma = Range("b" & x).Value

.ZamTyp = Range("a" & x).Value

.ZamNumer = Range("c" & x).Value

.ZamLp = Range("d" & x).Value

End With

Wynik = 0

Wynik = XLDodajPozycje_12(IDDokumentu, ElemInfo)

If Wynik <> 0 Then

Wynik = MsgBox("Błąd dodawania pozycji: " & Wynik)

Exit Sub

End If

Next x

End Sub

Sub Wyloguj()

Wynik = 0

Wynik = XLLogout_12(Sesja)

If Wynik <> 0 Then

Wynik = MsgBox("Błąd wylogowywania: " & Wynik)

Exit Sub

End If

End Sub

Sub Przeksztalc_ZS()

Zaloguj

DodajNaglowek

DodajPozycje

ZamknijNaglowek

Wyloguj

End Sub

Dodaj Kontrahenta (.NET)

Dla programistów wykorzystujących platformę MS .NET został przygotowany plik assembly, zawierający deklaracje struktur oraz funkcji używanych w CDN XL API. Plik jest dostępny na stronie ComArch (w zasobach CDN XL). Obecna wersja jest wersją testową, ciągle rozwijaną. Plik należy dołączyć w referencjach projektu (w Microsoft Visual Studio .NET można to zrobić wybierając w menu Project/Add Reference).

using System;

using cdn_api;

namespace XLNowyKontrahent

{

class APIDodajKontrahenta

{

[STAThread]

static void Main(string[] args)

{

XLLoginInfo_12 Login = new XLLoginInfo_12();

Login.Wersja = 12;

Login.ProgramID = "API.NET";

Login.Baza = "maciek4n";

Login.OpeIdent = "ADMIN";

Login.OpeHaslo = "";

Int32 SesjaID = 0;

Int32 KontrahentID = 0;

int LoginResult = cdn_api.cdn_api.XLLogin(Login, ref

SesjaID);

if (LoginResult == 0)

{

XLKontrahentInfo_12 Kontrahent = new XLKontrahentInfo_12();

Kontrahent.Wersja = 12;

Kontrahent.Akronim = "Nowy Kontrahent";

int KontrahentResult =

cdn_api.cdn_api.XLNowyKontrahent(SesjaID,ref KontrahentID,Kontrahent);

}

cdn_api.cdn_api.XLLogout(SesjaID);

}

}

}

Wskazówki do API w C8

Ogólne wytyczne w zakresie konfiguracji

1. Do sprawdzenia są elementy związane z wymogami systemowymi.

2. Warunki związane z samym systemem ERP XL dla wszystkich systemów operacyjnych:

Użytkownik ASPNET musi być w grupie użytkownicy, użytkownik na którym działa

IIS i ASP musi mieć prawa do katalogu z systemem ERP XL - chodzi o to żeby ten

użytkownik miał uprawnienia do uruchomienia ERP XL. [/su_list]

3. Na systemach serwerowych (2003,2008, 2012) i VISTA, Win 7, 8 najlepiej utworzyć dla takiej aplikacji osobną pulę aplikacji. Użytkownik, na którym działa pula (domyślnie Usługa Sieciowa) musi mieć prawo do katalogu z systemem CDNXL, aby miał uprawnienia do uruchomienia systemu.

4. Dodatkowo funkcje API powinny być wołane w trybie wsadowym.

5. Na C8 – nowy interfejs – przed logowaniem do API trzeba zawołać poniższy kod.

//jeśli C8 wołana jest metoda z ClaRUN.dll

public class Cdnsys

{

static extern void AttachThreadToClarion(int _flag);

public void AttachThread()

{

try

{

AttachThreadToClarion(1);

}

catch (Exception){}

}

}

Powyższe AttachThreadToClarion trzeba wołać przy każdym podnoszeniu nowego wątku.

6. W zmiennej środowiskowej Path powinno być wskazanie w ścieżce na jeden folder z systemem ERP XL (jeżeli jest zawarte odwołanie do innych folderów z wcześniejszymi wersjami należy je usunąć a następnie zapisać zmiany i zrestartować komputer).

7. Trzeba wołać attachthread wg wskazań w dokumentacji (lub jak powyżej) do każdego

nowego wątku i nie używać async’a. Jeżeli XLLogin jest wołane w innym wątku niż

pozostałe funkcje API to ten wątek musi pozostać aktywny tak długo jak wołamy funkcje

API – nie można po jego zakończeniu wołać funkcji API.

8. AttachThreadToClarion woła się 1 raz po utworzeniu wątku .net ( w tymże utworzonym wątku) – czyli 1 raz na wątek (teoretycznie nie ma ograniczenia na ilość wywołań AttachThread). Po wywołaniu AttachThreadToClarion wątek .net i wątek Clariona to jest jeden i ten sam wątek, nie ma więc operacji odwrotnej do AttachThreadToClarion. Jak zakończy się wątek utworzony w .net to zakończy się również w Clarionie i obiekty wątkowe zostaną zwolnione.

Plik Konfiguracyjny

Plik konfiguracyjny aplikacji nie pojawia się automatycznie po stworzeniu projektu i należy go dodać samodzielnie. Wystarczy kliknąć prawym przyciskiem myszy na projekt, do którego chcemy dodać plik z konfiguracjami, następnie wybrać opcję “Add New Item” i w oknie wyboru typu pliku zaznaczyć “Application Configuration File”. Dalej podaje się jego nazwę – standardowo App.config i potwierdza wybór.

Logowanie do API poprzez usługę

Podczas startowania usługi ( np. realizacja zamówienia ZS dokumentem WZ) wołany jest XLLogin, czyli są ustawiane obiekty globalne m.in. kolekcje rodzajów kontrahentów, definicje dokumentów itd. (wszystkie rzeczy konfiguracyjne XL’a). Potem startuje nowy wątek, w którym są wystawiane dokumenty np. WZ. Podczas gdy startuje nowy wątek to część danych konfiguracyjnych kopiuje z wątku głównego (robiona jest kopia żeby wątki się nie blokowały na czas dostępu do danych w wątku głównym). Należy zwrócić uwagę na specyficzne zachowanie usług (jeżeli usługa zawiera metody OnStart, OnStop, AutoResetEvent, WaitOne) – przy jej uruchamianiu wołana jest metoda OnStart (jeśli w niej byłoby umieszczone logowanie do API) to wątek w którym OnStart został wywołany może być za chwilę zakończony, co pociąga za sobą zwolnienie obiektów globalnych ładowanych przy XLLogin. Od tego momentu nowo tworzone wątki generujące np. WZ nie mają skąd skopiować danych konfiguracyjnych.

Rozwiązaniem jest w metodzie OnStart uruchomienie nowego wątku, w którym jest logowanie do API i ustawienie po zalogowaniu aby wątek nie zakończył się. Można to zrobić za pomocą statycznego obiektu klasy AutoResetEvent i metody WaitOne. W metodzie OnStop usługi trzeba wtedy zawołać metodę Set na tym obiekcie (po wylogowaniu z API).

API a aplikacje działające w oparciu o webserwis

W architekturze serwera opartego o WCF i klienta, problemem dla clariona jest kończenie wątku głównego gdy proces się nie kończy – czyli z punktu widzenia systemu operacyjnego wszystko jest poprawnie, jest wątek główny samej usługi. Wątek ten nie jest jednak związany z clarionem, więc w clarionie dopiero wątek w którym następuje logowanie do API jest wątkiem głównym – po wylogowaniu wątek ten się kończy mimo iż proces nadal działa – czy z punktu widzenia clariona sytuacja niemożliwa do uzyskania – nie ma czegoś takiego jak proces bez żadnego wątku, dlatego tez z tego powodu co jakiś czas zgłaszane mogą być wyjątki.

Rozwiązaniem będzie przy starcie usługi wydzielenie jednego wątku, związanie go z clarionem (AttachThread…) i pozostawieniem aktywnym przez cały czas działania usługi. W wątku tym trzeba wywołać od razu XLLogin. I teraz można zrobić od razu XLLogout, lub pozostawić tą sesję aktywną i w niej wystawiać dokumenty z wątków tworzonych na żądanie klientów – będzie szybciej działać. Czyli teraz nie byłoby już wołania XLLogin,XLNowyDokument…, XLLogout za każdym razem, ale jedynie XLNowyDokument z ID sesji ustalonym w wątku pierwszym.

Trzeba tak zmodyfikować dodatek, żeby choć jeden wątek procesu był podłączony do wątku clarionowego, tak aby nie było sytuacji, w której proces jest aktywny a żaden wątek nie jest połączony z clarionem. To wymaganie nie dotyczy okresu aktywności przed pierwszym wywołaniem AttachThreadToClarion.

Możliwe problemy do weryfikacji:

Connection string

Po zmianach w API XLPolaczenie nie zwraca automatycznie danych odnośnie połączenia. Funkcja API zwraca niezbędne dane do połączeń w aplikacji uzupełnione w tabeli cdn.Konfig i Kon_Numer = -137, Kon_Komentarz = ‘ConnectionString’.

Od wersji 2019.0 XLPolaczenie zwraca dane z funkcji skalarnej CDN.PodajDodatokwyConnectString – co pozwala na dynamiczną weryfikację połączenia, w przeciwieństwie do stałej danej wpisanej w CDN.Konfig.