Wprowadzenie
W przypadku niektórych zadań związanych z programowaniem i administracją Comarch ERP Enterprise konieczne jest wykonywanie programów Java z linii poleceń w kontekście serwera aplikacji systemu ERP (SAS). W tym celu każdy SAS posiada zintegrowany Toolshell. W shellu, polecenia można wprowadzać interaktywnie, można je podsumować w skrypty i wykonać. Podobnie jak w przypadku aplikacji działających w tle, polecenia Toolshell są często używane do wykonywania potencjalnie długotrwałych działań. Ponadto Toolshell jest również dostępna, jeśli serwer sieciowy SAS nie jest lub nie został jeszcze uruchomiony lub nie można go uruchomić. Jest to szczególnie pomocne m.in. podczas instalacji.
Grupa docelowa
- Programiści aplikacji
- Administratorzy systemu
- Konsultanci techniczni
Opis
Po uruchomieniu SAS domyślnie uruchamiany jest Toolshell. Wejście i wyjście odbywa się z poziomu konsoli wirtualnej maszyny Java. W zintegrowanym Shellu można wykonać dowolną liczbę poleceń jedno po drugim bez konieczności każdorazowego restartowania SAS. Zmiany w obiektach biznesowych i klasach są widoczne dla Toolshell dopiero po ponownym uruchomieniu.
Użytkownik
Toolshell wykonuje polecenia w sesji Comarch ERP Enterprise. W ramach sesji aktywny użytkownik Comarch ERP Enterprise jest domyślnie przypisany do zalogowanego użytkownika systemu operacyjnego, pod którym SAS został uruchomiony. W tym celu w konfiguracji systemu należy zdefiniować dla użytkownika odpowiednią identyfikację typu Nazwa użytkownika Windows. Alternatywnie można jawnie określić użytkownika Comarch ERP Enterprise, który ma być używany podczas uruchamiania serwera aplikacji za pomocą parametru -toolUser:<user>. Jeśli nie można określić użytkownika na podstawie użytkownika systemu operacyjnego lub jeśli nieprawidłowy użytkownik został określony za pomocą parametru -toolUser, Toolshell nie zostanie uruchomiony. W takim przypadku można go ponownie uruchomić tylko poprzez ponowne uruchomienie.
Uruchomienie bez serwera WWW
Jeśli parametr -tool jest określony podczas uruchamiania SAS, zintegrowany serwer WWW nie jest uruchamiany. Skraca to czas wymagany do uruchomienia serwera aplikacji systemu ERP. W takim przypadku polecenia mogą być wykonywane w Toolshell , ale nie jest możliwe zalogowanie się za pomocą przeglądarki internetowej. W takim przypadku serwer WWW można również uruchomić później za pomocą poleceń strsws lub wrksws.
Uruchomienie z aktywną bazą danych OLTP
W przypadku niektórych aplikacji demonstracyjnych (wprowadzenie programistyczne), aktywna baza danych OLTP musi być ustawiona dla sesji Toolshell w celu otwarcia fikcyjnej transakcji. Jest to możliwe dzięki opcji -toolDatabase:<Baza danych>. To ustawienie nie jest powiązane z parametrami narzędzi do tworzenia/kopiowania/generowania baz danych.
Wykonywanie skryptu podczas uruchamiania
Jeśli plik o nazwie autoexec.scl znajduje się w katalogu serwerów tego SAS podczas uruchamiania serwera aplikacji, plik ten jest wykonywany za pomocą polecenia call. Można tworzyć, edytować i usuwać plik autoexec.scl za pomocą narzędzia wrkautexc.
Plik autoexec.scl nie jest wykonywany, jeśli polecenie zostanie wydane po uruchomieniu serwera aplikacji.
Można wywołać kilka restartów w pliku autoexec.scl za pomocą następujących poleceń:
- restart – pozwala na restart serwera aplikacji, parametry startowe pozostają niezmienione
- restartUpgradeMode – wykonywany jest restart serwera aplikacji w trybie aktualizacji
- restartNoUpgradeMode – następuje restart serwera aplikacji bez aktualizacji
- exit – kończy wykonywanie skryptu; skrypty zawierające restarty są często kończone poleceniem –exit.
Jeśli utworzony zostanie plik autoexec.scl bez narzędzia wrkautexc, utworzony zostanie plik autoexec.scl.tmp z oryginalną zawartością. Natomiast plik autoexec.scl jest zmieniany, jeśli zawiera polecenia -restart lub -exit. Oba pliki są usuwane za pomocą poleceń: -exit lub wrkautexc -delete. Jeśli wywołanie pliku autoexec.scl zostanie anulowane, można również usunąć pliki ręcznie.
Polecenia
Toolshell ma wbudowane polecenia, narzędzia i polecenia zewnętrzne. Oprócz rzeczywistych poleceń, dla uproszczenia można również zdefiniować aliasy dla poleceń wraz z parametrami. Można uzyskać listę wszystkich dostępnych poleceń wpisując help. Podczas aktualizacji serwera aplikacji ze względów bezpieczeństwa dostępna jest ograniczona liczba poleceń.
Zestaw poleceń dostępnych w Toolshell nazywany jest językiem poleceń systemu ERP (SCL). Sekwencję poleceń można podsumować w pliku skryptu z rozszerzeniem .scl i wykonać jeden po drugim za pomocą polecenia call. Ta opcja definiowania skryptów jest szczególnie przydatna w przypadku powtarzających się zadań administracyjnych. Linie komentarza można wstawić w celu dodania zawartości plików skryptów. Zaczynają się one od # lub // i są ignorowane podczas wykonywania pliku skryptu.
wrkmle -delete -all
Oprócz interaktywnego wprowadzania danych w Toolshell, każde polecenie może być również wykonane bezpośrednio po uruchomieniu serwera aplikacji systemu ERP. W takim przypadku serwer aplikacji systemu ERP jest ponownie zamykany po wykonaniu polecenia. Wyjątkiem są wbudowane polecenia load i call, które mogą być używane do ładowania własnych definicji poleceń lub wykonywania skryptu bezpośrednio podczas uruchamiania. Serwer aplikacji nie jest automatycznie zamykany po wykonaniu polecenia.
Parametry
Z wyjątkiem poleceń wbudowanych, wszystkie polecenia mają co najmniej jeden parametr. Parametry są określane w postaci -parameterName:Value. Wielkie i małe litery są ignorowane podczas wprowadzania nazw parametrów. Określone wartości parametrów muszą być umieszczone w podwójnych cudzysłowach, jeśli zawierają spacje, np: chgsas -sas:LOCALHOST -description: „Local Server”
Jeśli wartość ma być określona dla parametru, który sam zawiera podwójne cudzysłowy, muszą one być oznaczone przedrostkiem \, np: chgsas -sas:LOCALHOST -description: „Local Server \”Demo\””
Wywołanie polecenia bez parametrów zawsze wyświetla krótką pomoc dla polecenia (szczegóły w rozdziale: Aliasy). Każdy parametr ma typ i jest parametrem obowiązkowym lub opcjonalnym. Parametry opcjonalne zazwyczaj mają również wartość domyślną. Niektóre parametry mogą być podawane wielokrotnie, zawierać znak * jako symbol wieloznaczny lub oba razem, np: dspusr -user:ABC -user:DEF -user:D*
Dla wszystkich poleceń, które wymagają nazwy katalogu lub nazwy pliku, należy podać ścieżki w systemie plików lokalnego serwera aplikacji.
W systemie istnieją następujące typy parametrów:
| Typ | Opis |
| <boolean> | Wartość logiczna, która może być opcjonalna, możliwe wartości to true i false. |
| <bool> | Wartość logiczna. Określenie parametru odpowiada wartości true, pominięcie parametru odpowiada wartości „false. Dla parametrów typu <bool>, których domyślną wartością jest true, nazwa parametru zmienia się na -no<parameter. |
| <vs> | Valueset (zestaw wartości). Możliwe wartości i ich znaczenie są wyświetlane w pomocy parametru. Wyboru dokonuje się poprzez wprowadzenie liczby. |
| <short> | Liczba całkowita. Liczby całkowite są określane jako ciąg cyfr bez znaków grupujących. |
| <int> | Liczba całkowita. Liczby całkowite są określane jako ciąg cyfr bez znaków grupujących. |
| <long> | Liczba całkowita. Liczby całkowite są określane jako ciąg cyfr bez znaków grupujących. |
| <string> | Tekst o ograniczonej długości, np. opis. Jeśli tekst zawiera spacje, należy użyć podwójnych cudzysłowów. |
| <id> | Tekst o ograniczonej długości, który reprezentuje identyfikator jednostki biznesowej, np. nazwę serwera aplikacji systemu ERP lub bazy danych. Jeśli tekst zawiera spacje, należy użyć podwójnych cudzysłowów. Identyfikatory są zawsze automatycznie konwertowane na wielkie litery podczas wykonywania polecenia. Odpowiada to zachowaniu pól GUI dla identyfikatorów, które zawsze konwertują wszystkie litery na wielkie, niezależnie od danych wprowadzonych przez użytkownika. |
| <tekst> | Tekst o nieograniczonej długości, np. ścieżka do pliku. Jeśli tekst zawiera spacje, należy użyć podwójnych cudzysłowów. |
| <guid> | Identyfikator GUID w notacji szesnastkowej lub Microsoft. |
| <d> | Ścieżka do istniejącego katalogu w systemie plików lokalnego serwera aplikacji. |
| <duration> | Czas trwania (czas). Specyfikacja ma postać 1 h 30 m lub 1 godzina 30 minut. Domyślna wartość wyświetlana jest zawsze w milisekundach. |
| <date> | Data w postaci zlokalizowanej zgodnie z ustawieniami użytkownika, np. 1.1.2024. Dozwolone są również wpisy względne, np.+1, dzisiaj lub jutro.Strefa czasowa, do której odnoszą się dane wejściowe, zależy od konkretnego polecenia. Na przykład może być określona przez kalendarz systemowy lub kalendarz firmowy. |
| <dateUntil> | Analogicznie jak typ <date> jednak w tym przypadku jest to data lokalna. |
| <time> | Data z oryginalnym czasem w formie zlokalizowanej zgodnie z ustawieniami użytkownika, np. 1.1.2024 12:00. Strefa czasowa, do której odnosi się wejście, zależy od konkretnego polecenia. Może być na przykład określona przez kalendarz systemowy lub kalendarz firmowy. |
| <timeStamp> | Znacznik czasu w formie zlokalizowanej zgodnie z ustawieniami użytkownika, np. 1.1.2024 12:00. Strefa czasowa, do której odnoszą się dane wejściowe, jest strefą czasową kalendarza aktywnego w sesji. W Toolshell jest to kalendarz systemowy. |
Wbudowane polecenia
Wbudowane polecenia są częścią Toolshell i są zawsze dostępne niezależnie od uprawnień. Wbudowane polecenia zazwyczaj nie mają parametrów lub mają tylko jeden parametr. Wywołanie bez parametrów wyświetla listę, a wywołanie z parametrami wykonuje akcję, np:
- help
- help endsas
- call C:\semiramis\autostart.scl
- call /opt/cisag/semiramis/autostart.scl
Polecenie alias
Polecenie to służy do wylistowania lub zdefiniowania aliasu. Aliasy mogą być używane do definiowania skrótów często używanych poleceń wraz z ich parametrami.
| Parametr | Opis |
| (brak) | Wyświetla listę wszystkich zdefiniowanych aliasów. |
| <name> <command> <option 1>…<option n> | Definiuje nowy alias o nazwie <name>. Jeśli zostanie wywołany, zostanie rozwinięty do <command> <option 1>…<option n> i wykonany. |
alias example2 type „C:/boot.ini”
alias example3 type „C:/Documents and Settings/\”Test.txt\””
Polecenie call
Polecenie to wykonuje wszystkie polecenia zapisane w pliku. Można użyć echo on i echo off, aby kontrolować, czy wykonywane polecenia są wyświetlane.
| Parametr | Opis |
| <filename> | Plik, którego polecenia mają zostać wykonane. |
| <parameter 1>…<parameter n> | Parametry wywołania pliku. Jeśli określono parametry, ciąg {0} zostanie zastąpiony pierwszym parametrem, {1} drugim i tak dalej. |
Polecenie exit
Polecenie exit anuluje wykonywanie wszystkich dalszych poleceń.
Polecenia iferror, else i endif
Polecenie iferror sprawdza, czy wystąpił błąd podczas ostatniego wykonywanego polecenia. Jeśli wystąpił błąd, wykonywanie jest kontynuowane. Jeśli nie wystąpił żaden błąd, wszystkie linie aż do iferror odpowiadające else lub endif są pomijane.
chkimp -codeClass:APP
iferror
echo “No APP code refreshes“
else
imprfr -codeClass:APP -all
…
endif
Polecenia onerror
Polecenie onerror stop zatrzymuje wykonywanie wszystkich dalszych poleceń w pliku, gdy tylko wystąpi błąd podczas wykonywania polecenia.
Polecenie onerror continue wykonuje inne polecenia w pliku, jeśli wystąpił błąd.
Stałe dla wyrażeń
Następujące stałe są dostępne dla wyrażeń z if lub {@}:
| Nazwa | Typ danych | Opis |
| errors | Boolean | True, jeśli podczas wykonywania ostatniego polecenia wystąpił błąd. |
| runtime | Number | Czas trwania wykonania ostatniego polecenia w milisekundach. |
| server | String | Nazwa serwera aplikacji |
| system | String | Nazwa systemu |
| fileServerDirectory | String | Katalog roboczy serwera aplikacji |
| systemUsage | String | Zastosowanie systemu |
| versioningLevel | Number | Poziom wersji systemu |
| args | String[] | Lista parametrów, które zostały przekazane za pomocą polecenia call. |
Polecenia if, else i endif
Polecenie if sprawdza dowolny warunek w języku skryptowym Worflow. Jeśli warunek jest spełniony, wykonanie jest kontynuowane. Jeśli warunek nie jest spełniony, wszystkie linie aż do if pasujące do else lub endif są pomijane.
if runtime<1000
echo „Fast”
else
echo „Slow”
endif
if size(args)<>2
echo “Parameters <A> <B> expected“
endif
Wyrażenia {@ }
W poleceniu call można używać dowolnych wyrażeń języka skryptowego Workflow. Wyrażenia są wprowadzane przez {@ i kończone przez }. Wynik wyrażenia jest konwertowany na ciąg znaków i zastępuje całe wyrażenie.
echo {@ 1+1}
{@ „dspdir -f: „+ args[0]}
Polecenie help
Polecenie to służy do wyświetlania listy wszystkich dostępnych poleceń lub pomocy do danego polecenia. Wywołanie polecenia bez parametrów lub z pojedynczym parametrem -help zawsze wyświetla krótką pomoc dla polecenia (szczegółowe informacje znajdują się w rozdziale Aliasy). Obejmuje ona listę parametrów, ich typ i kolejność, a także ich krótki opis oraz, jeśli są dostępne, zakres wartości, wartość domyślną i przykład składni wejściowej. Krótka pomoc jest również wyświetlana, jeśli w wartościach parametrów występują błędy składniowe lub jeśli parametry oznaczone w opisie jako parametry obowiązkowe nie zostały określone.
Można użyć wbudowanego polecenia help, aby wywołać rozszerzoną pomoc dla polecenia. Zawiera ona inny sposób wyświetlania parametrów oprócz informacji zawartych w skróconej pomocy:
- nazwa polecenia
- opis polecenia
- typ polecenia, np. alias
- struktura, do której przypisane jest polecenie
- ustawienia wyświetlania i wsparcie polecenia
- treść polecenia
- bezpośrednia pomoc polecenia
- bezpośrednia pomoc dla wszystkich parametrów
Aby wyświetlić bezpośrednią pomoc dla jednego lub więcej parametrów polecenia, należy wprowadzic wymagane parametry i parametr -help dla aktualnego polecenia.
| Parametr | Opis |
| (brak) | Wyświetla listę wszystkich dostępnych poleceń. |
| body | Wyświetlana jest treść polecenia. Wyświetlana zawartość zależy od typu polecenia w przypadku:
|
| all | Wyświetla wszystkie dostępne polecenia. Wyświetlane są również polecenia, które nie są zalecane lub nie powinny być używane. Korzystanie z tych poleceń odbywa się na własną odpowiedzialność, chyba że ich wykonanie zostanie zalecone przez zespół Asysty Technicznej Comarch ERP Enterprise. |
| <command> | Zapewnia pomoc dla polecenia. Taki sam rezultat zostanie uzyskany po wpisaniu komendy z parametrem -?. Można również użyć znaku * jako symbolu zastępczego w nazwie polecenia. W takim przypadku wyświetlone zostaną wszystkie polecenia pasujące do wzorca wyszukiwania, np. crt* lub *obj. |
help
help crt*
help -body -all rgz*
help crtbo
crtusr
crtusr -help
crtusr -email -type -help
Polecenie echo
Polecenie echo może wyświetlać ciąg znaków na konsoli i kontrolować wyjście wiersza poleceń dla call.
Za pomocą polecenia echo on można wyświetlić na konsoli każde polecenie wykonane za pomocą call podczas wywoływania skryptu. Za pomocą polecenia echo off polecenia wykonywane za pomocą call nie są wyprowadzane na konsolę.
Wszystkie pozostałe parametry polecenia echo są wyświetlane w nowej linii na konsoli.
Polecenie hist
Toolshell zapisuje historię 30 ostatnio wykonanych poleceń. Numery zarejestrowanych poleceń mieszczą się w zakresie od 1 do 30. Jeśli wykonano więcej niż 30 poleceń, najstarsze polecenie jest usuwane z historii, a numery wszystkich pozostałych poleceń są odliczane w dół o wartość 1.
Polecenie hist służy do wyświetlania lub wywoływania poleceń z historii. Specyfikacja hist 0 powtarza ostatnią wykonaną komendę. Jest to przydatne, jeśli konsola wirtualnej maszyny Java nie ma własnej funkcji historii.
| Parametr | Opis |
| (brak) | Wyświetla ostatnio wprowadzone polecenia. Dla każdego polecenia wyświetlany jest numer. |
| 0 | Wywołuje ostatnio wykonane polecenie. |
| <number> | Wywołuje poprzednio wykonane polecenie o numerze <number>. |
hist 0
hist 30
Polecenie load
Polecenie ładuje listę dodatkowych poleceń z pliku lub obiektu deweloperskiego typu File. Jeśli określona nazwa pliku zaczyna się od com., podejmowana jest próba załadowania odpowiedniego obiektu deweloperskiego typu File. Struktura zawartości pliku została opisana w rozdziale Polecenia zewnętrzne.
| Parametr | Opis |
| <filename> | Plik, z którego mają zostać załadowane definicje poleceń zewnętrznych. |
Polecenie set
Polecenie służy do wyświetlania lub ustawiania właściwości Java serwera aplikacji.
| Parametr | Opis |
| (brak) | Wyświetla wszystkie właściwości Java, dla których zdefiniowano wartość. |
| <name>=<value> | Ustawia właściwość Java o nazwie <name> na wartość <value>. |
| -filter:<wzorzec z „*”> | Wyświetla listę właściwości Java, które pasują do wzorca wyszukiwania i dla których zdefiniowano wartość. |
| -runtime:on | Aktywuje pomiar czasu wykonywania poleceń Toolshell. Po każdym poleceniu wyświetlany jest czas wymagany do jego wykonania. |
| -runtime:off | Wyłącza pomiar czasu wykonywania poleceń Toolshell. |
set -filter:com.cisag.*
set -runtime:on
Polecenie type
Wyświetla bezwzględną ścieżkę do pliku i strona po stronie jego zawartość na konsoli. Wyjście może zostać przerwane lub kontynuowane po każdej stronie.
| Parametr | Opis |
| <filename> | Plik, który ma zostać wyświetlony. Plik jest najpierw wyszukiwany w systemie plików. Jeśli tam nie istnieje, podejmowana jest próba znalezienia pliku w bieżącej ścieżce klasy. Jest to przydatne na przykład do wyprowadzania plików właściwości. |
type system.properties
Narzędzia (Tools)
Narzędzie jest aplikacją typu Tool. Narzędzia są zdefiniowane jako obiekty deweloperskie i podlegają normalnym uprawnieniom dla aplikacji. System nazw narzędzi oparty jest na nomenklaturze IBM i5:
| Narzędzie | Znaczenie | Opis |
| crt<obj> | create <obj> | Utwórz <obj>, Wygeneruj <obj> |
| chg<obj> | change <obj>Z | Zmień <obj> |
| chk<obj> | check <obj> | Sprawdź <obj> |
| dsp<obj> | display <obj> | Wyświetl <obj> |
| dlt<obj> | delete <obj> | Usuń <obj> |
| add<obj1><obj2> | add <obj1> <obj2> | Dodaj <obj1> <obj2> |
| rmv<obj1><obj2> | remove <obj1> <obj2> | Usuń <obj1> <obj2> |
| rgz<obj> | reorganize <obj> | reorganizuj <obj> |
| wrk<obj> | work <obj> | Pracuj z <obj> |
| exp<obj> | export <obj> | Eksportuj <obj> |
| imp<obj> | import <obj> | Importuj <obj> |
| str<obj> | start <obj> | Rozpocznij <obj> |
| end<obj> | end<obj> | Zakończ <obj> |
Polecenia zewnętrzne
Polecenia zewnętrzne są definiowane poprzez załadowanie pliku właściwości. Domyślnie obiekt pliku com.cisag.sys.kernel.tools.CisToolshell.properties jest ładowany ze ścieżki klasy podczas uruchamiania Toolshell. Zewnętrzne polecenia są zdefiniowane w pliku w następującej formie:
command=com.cisag.xyz.ABC/Framework/¬Description
Oprócz nazwy klasy, w definicji można również określić parametry. Klasa musi mieć statyczną metodę main(String[]). Jest ona wywoływana podczas wykonywania zewnętrznego polecenia. Oprócz rzeczywistych definicji poleceń, pliki mogą również zawierać linie komentarzy. Zaczynają się one od # lub // i są ignorowane podczas wykonywania poleceń. Można użyć polecenia load, aby załadować własne definicje poleceń dla zewnętrznych poleceń z pliku.
Jeśli istnieje potrzeba użycia należy:
Aliasy
Nowy alias definiuje się poleceniem alias newalias xyz -option1 -option2. Comarch ERP Enterprise dostarcza szereg predefiniowanych aliasów.
| Alias | Opis |
| ci | jest aliasem dla narzędzia chkin. |
| co | jest aliasem dla narzędzia chkout. |
| dbgmsg | jest aliasem dla narzędzia dbgmsgmgr z parametrami -logLevel:2 -traceLevel:2. Za jego pomocą można bardzo łatwo i szybko aktywować rejestrowanie wszystkich komunikatów na konsoli, w tym ślad stosu lokalizacji programu, który wysłał komunikat, w celu analizy błędów. Dezaktywację można następnie przeprowadzić za pomocą wywołania dbgmsgmgr -logLevel:35 -traceLevel:35. |
| restart | jest aliasem dla narzędzia endsvr z parametrem -restart. |
| stop | jest aliasem dla narzędzia endsvr z parametrem -stop. |
| strsws | jest aliasem dla narzędzia wrksws z parametrem -start. |
Narzędzia z możliwością odblokowania
Niektóre narzędzia powinny być używane tylko po konsultacji z Asystą Techniczną Comarch ERP Enterprise, aby uniknąć nieoczekiwanych konsekwencji, takich jak utrata danych. W tym celu do wywołania niektórych narzędzi wymagany jest ograniczony czasowo kod aktywacyjny. Możliwe jest, że tylko poszczególne parametry narzędzia są chronione w ten sposób, aby narzędzie mogło być używane z innymi parametrami bez podawania kodu aktywacyjnego.
Gdy wywołane zostanie takie narzędzie, pojawi się okno w którym należy wprowadzić kod aktywacyjny. Należy wpisać kod odblokowujący z parametrem -unlockCode:<string>. Kod odblokowujący można uzyskać w dziale Asysty Technicznej Comarch ERP Enterprise.
