InsERT GT Własne COM 1.0

InsERT GT Własne COM 1.0 Autor: Jarosław Kolasa, InsERT Wstęp... 2 Dołączanie zestawień własnych do systemu InsERT GT... 2 Sposób współpracy rozszerzeń z systemem InsERT GT... 2 Rozszerzenia standardowe COM... 3 Rozszerzenia WSC... 3 Rozszerzenia zrealizowane jako komponenty.net... 3 Własne COM interfejs programisty... 5 InsERT GT... 5... 5 Zestawienie... 8... 8 2004 InsERT sp. z o.o. 1

Wstęp Niniejszy dokument przeznaczony jest dla twórców aplikacji zintegrowanych z systemem InsERT GT zwanych rozszerzeniami lub zestawieniami własnymi COM. Komunikacja z nimi jest zrealizowana w technologii COM. Daje to moŝliwość pracy w określonym kontekście systemu InsERT GT, czyli z aktywnym podmiotem, okresem, magazynem, zalogowanym uŝytkownikiem bez konieczności dodatkowego określania tych parametrów. Dodatkowo osiągalne są wszelkie inne informacje z bazy danych oraz moŝliwe jest dowolne kształtowanie interfejsu uŝytkownika. Ten sposób rozszerzania funkcjonalności systemu InsERT GT nie przewiduje dostępu do jego wewnętrznych obiektów. MoŜliwe są jedynie bezpośrednie operacje na danych w bazie. Zapewniony jest do nich pełny dostęp. Sposób organizacji danych opisuje osobny dokument Dokumentacja bazy danych. Dołączanie zestawień własnych do systemu InsERT GT Zestawienia wykonane w technologii COM wg specyfikacji moŝna dołączyć do systemu InsERT GT i wykorzystywać za pomocą modułu Zestawienia. Pozwala on na dodawanie i usuwanie (tylko z programu, a nie z dysku) własnych zestawień wykonanych w technologii COM. W celu dołączenia własnego zestawienia naleŝy wybrać z menu Operacje opcję Dodaj zestawienia COM, a następnie wskazać plik zawierający zestawienie (jedno lub więcej). System wówczas rejestruje wskazane zestawienia i umieszcza na liście dostępnych zestawień własnych o ile zestawienie moŝe być w danym programie uruchamiane (metoda Programy). Sposób współpracy rozszerzeń z systemem InsERT GT InsERT GT udostępnia interfejs, za pomocą którego moŝna uzyskać wszystkie informacje na temat kontekstu pracy. Moduł zestawienia dostarczany przez niezaleŝną firmę moŝe zawierać więcej niŝ jedno rozszerzenie. KaŜde z rozszerzeń musi udostępniać interfejs umoŝliwiający uruchamianie go z InsERT GT (z modułu Zestawienia). Ogólny schemat współpracy przedstawia poniŝszy rysunek. InsERT GT Moduł Zestawienia Rozszerzenie/ Zestawienie w łasne COM 1 baza danych podmiotu Rozszerzenie/ Zestawienie w łasne COM 2 Rozszerzenie/ Zestawienie w łasne COM n Uruchomienie dostarczonego zestawienia własnego COM jest moŝliwe po uprzednim zarejestrowaniu tego rozszerzenia w InsERT GT (moŝna to zrobić z poziomu modułu Zestawienia za pomocą opcji Operacje-Dodaj własne COM). Zarejestrowanie polega na zapisaniu informacji w rejestrze systemowym pod kluczem: <klucz_insert_gt>\wlasnecom\<progid_komponentu_rozszerzenia> 2004 InsERT sp. z o.o. 2

następujących trzech wartości ciągu (REG_SZ): Nazwa Opis Plik nazwa rozszerzenia do wyświetlenia na liście opis realizowanej funkcjonalności rozszerzenia lokalizacja fizyczna kodu rozszerzenia oraz wartości DWORD (REG_DWORD): Programy programy, w których ma być widoczne rozszerzenie. Uruchomienie rozszerzenia polega w pierwszym kroku na stworzeniu przez InsERT GT komponentu o podanym ProgID równym nazwie klucza w rejestrze systemowym. Warunkiem stworzenia takiego obiektu jest oczywiście uprzednie zarejestrowanie w systemie komponentu COM. Kolejnym krokiem przy uruchamianiu rozszerzenia jest wywołanie funkcji Wykonaj i oczekiwanie na jej zakończenie. Wewnątrz funkcji Wykonaj odbywa się zaprogramowana przez twórcę rozszerzenia interakcja z uŝytkownikiem, obliczenie i przedstawianie wyników działania rozszerzenia. Rozszerzenia standardowe COM Przy dodawaniu rozszerzeń zrealizowanych jako standardowe komponenty COM z poziomu Zestawień (za pomocą opcji Dodaj), InsERT GT rejestruje je w systemie przez wywołanie funkcji DllRegisterServer z <nazwa_modułu>.dll. Następnie dodaje je do listy zestawień (rejestruje w InsERT GT). Komponenty, które są zawarte w modułach nieeksportujących tej metody muszą być zarejestrowane poprawnie w systemie przed uruchomieniem opcji Dodaj. MoŜe to realizować np. instalator stworzonego rozszerzenia. Rozszerzenia WSC Przy dodawaniu rozszerzeń zrealizowanych jako Windows Script Component z poziomu Zestawień (za pomocą opcji Dodaj), InsERT GT rejestruje je w systemie przez wywołanie funkcji DllInstall z biblioteki scrobj.dll ze wskazaniem na plik WSC. Biblioteka scrobj.dll jest serwerem komponentów skryptowych WSC. Następnie dodaje je do listy zestawień (rejestruje w InsERT GT). W przypadku komponentów WSC nie jest moŝliwe zaimplementowanie metod jakiegokolwiek interfejsu, w szczególności interfejsu. W związku z tym dopuszcza się ich realizację jako zwykłych metod obiektu. W procesie uruchamiania zestawienia są one wywoływanych po nazwie za pomocą metod interfejsu IDispatch (GetIDsOfNames, Invoke). Przy tworzeniu rozszerzeń WSC nieoceniony jest WSC Wizard dostępny pod adresem: http://msdn.microsoft.com/downloads/sample.asp?url=/msdn-files/027/001/788/msdncompositedoc.xml Rozszerzenia zrealizowane jako komponenty.net Przy dodawaniu rozszerzeń zrealizowanych jako komponenty.net z poziomu Zestawień (za pomocą opcji Dodaj), InsERT GT dodaje je tylko do listy zestawień (rejestruje w InsERT GT). Dlatego muszą być juŝ wcześniej poprawnie zarejestrowane w systemie. Do tego celu słuŝy narzędzie regasm.exe. Przykłady wykorzystania regasm.exe do zarejestrowania w systemie własnych zestawień w postaci komponentów.net zawartych w bibliotece WlasneNET.dll: A. Zarejestrowanie rozszerzeń w postaci biblioteki prywatnej dla aplikacji: Krok 1. Skopiowanie WlasneNET.dll do folderu System w miejscu zainstalowania InsERT GT. Krok 2. Uruchomienie w linii poleceń komendy regasm.exe WlasneNET.dll. B. Zarejestrowanie rozszerzenia w taki sposób jak inne komponenty COM (wspólne dla całego systemu): Krok 1. Skopiowanie WlasneNET.dll do dowolnego folderu w systemie plików, gdzie jest moŝliwy dostęp uŝytkowników korzystających z InsERT GT. Krok 2. Uruchomienie w linii poleceń komendy regasm.exe /c WlasneNET.dll. 2004 InsERT sp. z o.o. 3

UWAGA! Oprócz dystrybucji biblioteki z komponentami WlasneNET.dll naleŝy pamiętać o dostarczeniu równieŝ bibliotek Interop w to samo miejsce (do tego samego folderu). Ich liczba moŝe być róŝna w zaleŝności od zastosowanych rozwiązań. Jednak ze względu na wykorzystanie ADO i biblioteki typów z InsERT GT muszą być przynajmniej dwie: Interop.MSADO15.dll oraz Interop.ZestManLib.dll. Oczywiście po rejestracji rozszerzeń w systemie naleŝy dokonać odpowiedniego wpisu w rejestrach lub dodać własne zestawienia poprzez Zestawienia-Operacje-Dodaj wlasne COM. O udostępnianiu klientom COM komponentów.net więcej moŝna przeczytać pod adresem: http://msdn.microsoft.com/library/en-us/cpguide/html/cpconexposingnetframeworkcomponentstocom.asp 2004 InsERT sp. z o.o. 4

Własne COM interfejs programisty Biblioteka ZestMan.dll dostarczana wraz z InsERT GT zawiera definicje wszystkich interfejsów wykorzystywanych w integracji z rozszerzeniami. Nazwa UUID Opis ZestManLib 0DD7E584-C075-4654-9BC8-FC95FEF1F083 InsERT GT ZestMan 1.0 Type Library InsERT GT udostępniany ze strony InsERT GT. Nazwa UUID Opis 6BE4BFFA-694B-49E9-8697-720B88B6830C Informacje o bieŝącym podmiocie i instalacji oraz parametrach poszczególnych programów wchodzących w skład InsERT GT Pozwala uzyskać informacje o bieŝącym podmiocie, kontekście pracy i instalacji oraz parametrach poszczególnych programów wchodzących w skład InsERT GT Connection AO Baza danych bieŝącego podmiotu otwarta przez program (pełny dostęp). Demo AO Informacja, czy program pracuje w wersji demo. Program AO Informacja z którego programu uruchomiono zestawienie. WersjaBazyDanych AO Wersja bazy danych. FolderProgramu AO Folder programu. NazwaPodmiotu AO Nazwa podmiotu. PersonelIdentyfikator AO Identyfikator osoby z personelu zalogowanej do podmiotu. Personel AO Imię i nazwisko osoby z personelu zalogowanej do podmiotu. MagazynNazwa AO Nazwa bieŝącego magazynu. MagazynId AO Identyfikator bieŝącego magazynu. OkresDataOd AO Początkowa data bieŝącego roku obrachunkowego. OkresDataDo AO Końcowa data bieŝącego roku obrachunkowego. DataBlokady AO Data blokady okresu. A atrybut, O do odczytu Atrybut Connection Zwraca obiekt ADO Connection bieŝącego podmiotu otwarty przez program z pełnymi prawami dostępu. MoŜliwe są wszelkie operacje wykonywane na bazie danych. Tylko do odczytu. VC: HRESULT Connection( IDispatch** pval ); VB: obiekt.connection As Object Atrybut Demo Zwraca informację, czy program pracuje jest w wersji demonstracyjnej. Tylko do odczytu. VC: HRESULT Demo( VARIANT_BOOL* pval ); VB: obiekt.demo As Boolean 2004 InsERT sp. z o.o. 5

Atrybut Program Zwraca informację, z którego programu uruchomiono zestawienie. Tylko do odczytu. VC: HRESULT Program( LONG* pval ); VB: obiekt.program As Long Zwracana jest jedna z poniŝszych wartości: 1 - Subiekt 2 - Rachmistrz (KPIR) 4 - Rachmistrz (ryczałt) 8 - mikrogratyfikant Atrybut WersjaBazyDanych Zwraca informację o wersji bazy danych bieŝącego podmiotu. Tylko do odczytu. VC: HRESULT WersjaBazyDanych( BSTR* pval ); VB: obiekt.wersjabazydanych As String Atrybut FolderProgramu Zwraca informację, o miejscu zainstalowania uruchomionego programu. Tylko do odczytu. VC: HRESULT FolderProgramu( BSTR* pval); VB: obiekt.folderprogramu As String Atrybut NazwaPodmiotu Zwraca nazwę bieŝącego podmiotu. Tylko do odczytu. VC: HRESULT NazwaPodmiotu( BSTR* pval ); VB: obiekt.nazwapodmiotu As String Atrybut PersonelIdentyfikator Zwraca identyfikator osoby z personelu aktualnie zalogowanej do podmiotu. Tylko do odczytu. VC: HRESULT PersonelIdentyfikator( BSTR* pval ); 2004 InsERT sp. z o.o. 6

VB: obiekt.personelidentyfikator As String Atrybut Personel Zwraca imię i nazwisko osoby z personelu zalogowanej do podmiotu. Tylko do odczytu. VC: HRESULT Personel( BSTR* pval ); VB: obiekt.personel As String Atrybut MagazynNazwa Zwraca nazwę bieŝącego magazynu. Tylko do odczytu. VC: HRESULT Magazyn( BSTR* pval ); VB: obiekt.magazyn As String Atrybut MagazynId Zwraca identyfikator bieŝącego magazynu. Tylko do odczytu. VC: HRESULT MagazynId( LONG* pval ); VB: obiekt.magazynid As Long Atrybut OkresDataOd Zwraca początkową datę bieŝącego roku obrachunkowego. Tylko do odczytu. VC: HRESULT OkresDataOd( DATE* pval ); VB: obiekt.okresdataod As Date Atrybut OkresDataDo Zwraca końcową datę bieŝącego roku obrachunkowego. Tylko do odczytu. VC: HRESULT OkresDataDo( DATE* pval ); VB: obiekt.okresdatado As Date 2004 InsERT sp. z o.o. 7

Atrybut DataBlokady Zwraca datę blokady okresu. Tylko do odczytu. VC: HRESULT DataBlokady( VARIANT* pval ); VB: obiekt.datablokady As Variant Atrybut przyjmuje wartość NULL jeśli brak blokady okresu. Zestawienie ze strony zestawienia, wykorzystywany do rejestrowania i uruchamiania rozszerzenia przez system InsERT GT. Nazwa CLSID Opis D2B992DB-4C35-440c-AD64-45FFF669DE93 zestawienie własne, który musi być zaimplementowany przez przez zestawienie własne. Zawiera atrybuty potrzebne do poprawnego zarejestrowania rozszerzenia w systemie InsERT GT oraz metodę do uruchomienia z poziomu modułu Zestawienia. Opis AO Opis zestawienia. Nazwa AO Nazwa zestawienia. Programy AO Programy, w których zestawienie ma być widoczne. Wykonaj M Uruchamia zestawienie. A atrybut, O do odczytu, M metoda Atrybut Opis Opis zestawienia. Tylko do odczytu. VC: HRESULT Opis( BSTR* pval ); VB: obiekt.opis As String Atrybut Nazwa Nazwa zestawienia. Tylko do odczytu. VC: HRESULT Nazwa( BSTR* pval ); VB: obiekt.nazwa As String Atrybut Programy 2004 InsERT sp. z o.o. 8

Zwraca informację, w których programach zestawienie ma być widoczne. Tylko do odczytu. VC: HRESULT Programy( LONG* pval ); VB: obiekt.programy As Long Zwracana wartość musi być sumą wybranych spośród poniŝszych flag: 1 - Subiekt 2 - Rachmistrz (KPIR) 4 - Rachmistrz (ryczałt) 8 - mikrogratyfikant Metoda Wykonaj Uruchamia zestawienie. Wywoływana przez moduł zestawień własnych COM w celu wykonania zestawienia. VC: HRESULT Wykonaj( * pzestawieniecomdane ); VB: obiekt.wykonaj(pzestawieniecomdane As CoZestawienieComDane ) pzestawieniecomdane do obiektu utworzonego po stronie InsERT GT. Koniec. 2004 InsERT sp. z o.o. 9