Swagger UI i PASOE

Swagger UI jest narzędziem które umożliwia wizualizację zasobów API bez konieczności implementacji dodatkowych zewnętrznych aplikacji.

Swagger składa się z plików HTML, JavaScript i CSS, które dynamicznie generują dokumentację na podstawie interfejsu API.
Jest dostępny w PASOE począwszy od wersji OE 12.0 (domyślnie wyłączony). Od wersji OE 12.2 jest domyślnie włączony dla instancji deweloperskich – należy pamiętać aby nigdy nie włączać go w środowiskach produkcyjnych.

Dostęp do Swaggera jest z poziomu oemanagera (http://host:port/oemanager/), ale jeśli dostęp jest zabroniony, to wchodzimy z poziomu managera, czyli http://host:port/manager/, np. http://localhost:8813/manager.


Tutaj klikając oemanager dostajemy ekran dokumentacji Swaggera.


Ekran składa się z sekcji np. dla każdej warstwy transportowej,  Agent Manager, Session Manager i OEABL ManagerService.
Przechodzimy do tej drugiej i klikamy na GET /applications, następnie Try it out i Execute.


Dostajemy listę wszystkich aplikacji ABL dla instancji PASOE wraz z parametrami w postaci JSON. Listę tę można pobrać jako plik tekstowy.

Jeśli w OEABL ManagerService kliknę GET /applications/{AppName}/webapps i wpiszę nazwę aplikacji ABL, dostanę w podobnej postaci listę wszystkich aplikacji webowych dla tejże aplikacji.

Aby pobrać listę web servisów dla danej aplikacji webowej wybieram GET/applications/{AppName}/webapps/{WebAppName} i podaję nazwę aplikacji ABL i web serwisu.

Jak widać na obrazkach czasowniki GET nie są jedynymi do użycia. Można np. zaktualizować listę poprzez czasownik POST czy zerować metryki (DELETE).
Opcji jest bardzo wiele.

Migracja do PASOE

O PASOE sporo pisałem. Wiadomo, w OE12 nie ma już klasycznego AppServera i trzeba podjąć decyzję o migracji aplikacji, a przed decyzją dobrze jest poznać za i przeciw nowego produktu.
Teraz jednak powracam do tematu samej migracji w szerszym kontekście (pisałem o podstawach migracji w 2017).

Korzyść z nowego AppServera widać już podczas instalacji: możemy wybrać czy instalowana instancja będzie deweloperska czy produkcyjna. Dla tej ostatniej dodajemy w komendzie parametr -Z prod i mamy instalowanie instancji z implementacją silniejszych zabezpieczeń niż dla wersji deweloperskiej. O samych zabezpieczeniach nie będę pisał ponieważ temu tematowi poświęciłem tutaj kilka wpisów.

Następnym krokiem jest migracja ustawień, czyli pliku z właściwościami. Istniejący plik ubroker.properties musi zostać przekonwertowany na nowy format używany przez PASOE openedge.properties.
Kolejność działania jest następująca: najpierw uruchamiamy polecenie paspropconv, które konwertuje właściwości z pliku ubroker.properties do tymczasowego pliku ubrokername.oemerge. Plik ten można dopasować do naszych potrzeb i włączyć ustawienia naszej nowej instancji do pliku openedge.properties.

Komendę paspropconv uruchamiamy w podkatalogu conf dla instancji PASOE z przykładowymi parametrami, które są wymagane. Podwójne myślniki przed nazwą parametru wynikają stąd, że skrypt jest napisany w języku Perl.

--ubrokerPropsFile C:\classicapp\ubroker.properties 
--ubrokerName UBroker.AS.asbroker1 
--pasoeAppName myprod

Pierwszy parametr określa ścieżkę do pliku z właściwościami dla klasycznego AppServera, drugi jest nazwą instancji tego AppServera, wreszcie trzeci określa nazwę nowej instancji PASOE.
Po uruchomieniu komendy w katalogu conf zostały utworzone poniższe pliki:

Dla nas istotny jest plik .oemerge. Niemal całą jego zawartość stanowi przewodnik po migracji, zawierający sekcje np:
Tryby pracy (operating modes) – zawiera porady dotyczące migracji istniejących trybów pracy (state-reset, state-aware, stateless, statefree) na tryby pracy w PASOE. Omówione są proste instrukcje, realizujące ten etap migracji, które wiążą i zwalniają bieżącą sesję ABL (były omawiane na blogu kilka lat temu).
Procedury zdarzeniowe (event procedures) – omawiane są stare i nowe procedury (agentStartupProc, sessionStartupProcParam) związane z inicjalizacją agenta wielo-sesyjnego oraz każdej sesji ABL.

# paspropconv  v1.15 (MSWin32)
# 
# Input arguments:
# 
#   ubrokerPropsFile    = C:\classicapp\ubroker.properties
#   ubrokerMergeFile    = 
#   ubrokerName         = UBroker.AS.asbroker1
#   pasoeAppName        = myprod
#   pasoeWebAppName     = ROOT
#   pasoeMergeFile      = myprod.asbroker1.oemerge
#   pasoeSetEnvFile     = asbroker1_setenv
#   convNotesDBFile     = C:\OPENED~1\bin\paspropconv_notesdb.en
#   logFile             = paspropconv.log
#   loggingLevel        = 2
# 
# Operating Modes
# ---------------
# 
# The classic AppServer supports 4 operating modes:
#   state-reset
#   state-aware
#   stateless
#   statefree
# 
# In the classic AppServer, the operating mode is specified when the AppServer
# is deployed.  Consequently, all ABL sessions supported by the AppServer
# employ the same operating mode.
# 
# In PASOE, the operating mode of a session is not specified during deployment.
# As such, a single PAS server can support concurrent ABL sessions, each
# emulating the behavior of different classic operating modes.
# 
# To support the different types of operating mode behavior
# provided in the various classic modes, some ABL code modifications
# may be required.  It is recommended that these changes are made in 
# the PASOE sessionConnectProc () and
# sessionDisconnProc () event procedures.
.......
[AppServer.Agent.myprod]
    PROPATH=${CATALINA_BASE}/openedge,${CATALINA_BASE}/webapps/ROOT/WEB-INF/openedge,.....
    agentMaxPort=2202
    agentMinPort=2002
    keyAlias=
    keyAliasPasswd=
    keyStorePasswd=
    keyStorePath=${DLC}/keys/
    noSessionCache=0
    numInitialSessions=5
    sessionActivateProc=
    sessionConnectProc=
    sessionDeactivateProc=
    sessionDisconnProc=
    sessionExecutionTimeLimit=0
    sessionShutdownProc=
    sessionStartupProc=
    sessionStartupProcParam=
    sessionTimeout=180
    sslAlgorithms=
    sslEnable=0
.......

Ostatnia sekcja nie jest komentarzem – zawiera zestaw właściwości, które powinny zostać scalone z plikiem openge.properties dla nowej instancji serwera.

Dalsze porady dotyczą ręcznej konfiguracji wynikającej z różnic w ścieżkach dostępu, architektury systemu operacyjnego, zmiennych środowiskowych, połączeń z bazami danych itd.
Dla pełniejszych informacji warto pobrać i przeczytać dokument: Quick Start: Moving Your Classic AppServer Applications to the Progress® Application Server for OpenEdge®.

OpenEdge 12.3

Powróćmy do tematu związanego z OpenEdge, ponieważ już od pewnego czasu mamy na rynku nową wersję OE 12.3.
Zacznijmy od nowinki dla programistów; dodano nową, bardziej zwięzłą instrukcję definicji zmiennych. Do tej pory ile zmiennych chcieliśmy zdefiniować, tyle musieliśmy wstawić definicji. Obecnie zapis jest krótszy, a w jednej instrukcji można zdefiniować wiele zmiennych. Zmienne zdefiniowane poprzez nową instrukcję są zawsze NO-UNDO.

Następna nowinka związana jest z definicją tablicy (extentu) o nieokreślonym rozmiarze. Rozmiar ten można teraz określić podczas fazy runtime, nawet jeśli tablica ma przypisane wartości początkowe.

W ABLu wprowadzono także operatory przypisania (+=, -=, *=, /=) do wykonywania operacji i przypisywania
wartość, używając skróconej notacji.

Od 12.3 jeśli zachodzi potrzeba aktualizacji aplikacji ABL, przy czym ta aktualizacja jest związana z nowymi elementami schematu, nie trzeba już
restartować maszyny wirtualnej ABL (AVM).

W OpenEdge 12.3 dodano ciekawą opcję komendy PROUTIL: PROUTIL TABLEREORG – umożliwia to reorganizację pofragmentowanych danych w tabeli, podczas gdy sama tabela pozostaje dostępna dla operacji OLTP (przetwarzanie transakcji online). Nowy proces zastępuje długotrwałe operacje zrzutu i ładowania danych oraz odbudowy powiązanych indeksów. Rekordy tabeli muszą znajdować się w tym samym obszarze przechowywania typu II. Operacja ta obsługuje także tabele multi-tenant oraz podzielone na partycje.

Kolejne parametry mogą być modyfikowane online, tym razem dla brokera secondary.
Maximum Clients per Server (-Ma)
Maximum Dynamic Server (-maxport)
Minimum Clients per Server (-Mi)
Minimum Dynamic Server (-minport)
Message Buffer Size (-Mm)
Maximum Servers per Broker (-Mpb)
Pending Connection Time (-PendConnTime)

Zmiany parametrów można dokonać w R&D -> opcja 4. Administrative Functions -> 16. Adjust Startup Parameters.

Jest jeszcze kilka ciekawych zmian związanych z tzw. Continuous Operations, bezpieczeństwem, programowaniem, ale to już musicie poszukać w sieci sami.

JSON: wyświetlanie danych

W kilku wcześniejszych artykułach kończyliśmy rozważania na utworzeniu serwisu generującego dane JSON. URI do tych danych może posłużyć do integracji z innym systemem czy interfejsem wyświetlającym dane, najczęściej w języku JavaScript. Przypomnę dwa posty sprzed kilku lat:
Serwis OpenEdge – Telerik Kendo UI,
Rollbase i serwisy OpenEdge,
w których opisałem dwa produkty wyświetlające dane pochodzące z formatu JSON.

Istnieje wiele środowisk, w których możemy tworzyć front-end w JavaScript, ale dziś pokażę jak wyświetlić dane na dwóch prostych przykładach.
Weźmy JSON wygenerowany w poprzednim artykule. Struktura danych jest następująca dsCustomer.ttCustomer[i]… dane do pól rekordów.


Nie ma tutaj znaczenia czy plik JSON jest wygenerowany do katalogu. Dane w formacie JSON są przechowywane w pamięci przeglądarki.

W pierwszym przykładzie skorzystamy z metody getJSON, której pierwszym parametrem jest URI do danych JSON.

<!DOCTYPE html>
<html>

<body>

<h2>Customers</h2>
<div id="mydata"></div>

<script>

var getJSON = function(url, callback) {

var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'json';

xhr.onload = function() {

var status = xhr.status;

if (status == 200) {
callback(null, xhr.response);
} else {
callback(status);
}
};

xhr.send();
};

getJSON('http://localhost:8810/wh/web/pdo/whsrv/customer', function(err, data) {

if (err != null) {
console.error(err);
} else {

var text = `Last Name: ${data.dsCustomer.ttCustomer[1].CustNum}<br>
First Name: ${data.dsCustomer.ttCustomer[1].Name}`

document.getElementById("mydata").innerHTML = text;

}
});
</script>

</body>
</html>

Ten prosty skrypt wyświetla 2 pola z rekordu Customer, a dokładniej zmienną text, w której mogą znajdować się znaki formatujące.

Drugi przykład jest podobny, ale wykorzystuje bibliotekę jQuery. Tym razem wyświetlanych jest kilka rekordów (zmienna text) sformatowanych wg pliku css (nie zamieszczonego).

<!DOCTYPE html>
<html lang="en">
<head>
<title>JavaScript - read JSON from URL</title>

<script src="https://code.jquery.com/jquery-3.2.1.min.js">
</script>

<link rel="stylesheet" href="customers.css">
</head>

<body>
<h2>Customers</h2>
<div class="mydata"></div>

<script>
$.getJSON('http://localhost:8810/wh/web/pdo/whsrv/customer', function(edata) {

var text="<table>";
var i;

for(i = 1; i < 11; i++) {

text += "<tr><td>" +`${edata.dsCustomer.ttCustomer[i].CustNum}` + "</td><td>" +
`${edata.dsCustomer.ttCustomer[i].Name}` + "</td><td>" +
`${edata.dsCustomer.ttCustomer[i].City}` + "</td></tr>"
}
text += "</table>";

$(".mypanel").html(text);
});
</script>

</body>
</html>

 

Efekt widać poniżej.

Napiszcie o swoich przykładach wykorzystujących dane JSON na forum PUG Poland. Jak zapewne zauważyliście forum to zostało przeniesione razem z resztą Progress Communities do nowej lokalizacji, a starsze wątki zastały przeniesione do Archiwum.

Trzeba ponownie się zarejestrować.
 

Serwisy REST Webhandler po raz trzeci

W 2018 opisałem 2 przykłady serwisów REST Webhandler ABL. Dostęp do nich jest nie poprzez warstwę transportową REST lecz WEB.

Temat powraca ze względu na Wasze zainteresowanie tą metodą. Intuicyjnie, niektórzy uważają, że jest to lepszy sposób na budowanie serwisów po przejściu na serwer aplikacji PASOE, ze względu na to że są to serwisy napisane w języku ABL. Niektórzy uważają jednakże, że ten typ serwisów jest trudniejszy do wygenerowania w porównaniu z typowymi serwisami REST Data Object Service. Pokażę za chwilę, że serwisy z użyciem Web Handera (w skrócie WH) są również bardzo proste.
W niniejszym blogu znajdziecie 2 metody tworzenia typowych serwisów REST: Data Object Service oraz z mapowaniem elementów URI. Pierwsza metoda jest bardzo łatwa, ale ma pewne ograniczenia, druga bardziej elastyczna, ale wymagająca więcej pracy.

Z serwisami WH jest podobnie. To co pokazałem 2 lata temu, to trudniejsza, elastyczna metoda związana z napisaniem własnego web handlera. Jednakże, można użyć szybkiej, prostej metody Data Object Service, co teraz chciałbym pokazać.

Tworzymy projekt typy WEB. Zaznaczamy “Create a Data Object Service….”.

Możemy poprzestać na domyślnej nazwie aplikacji webowej, lub nadać własną: tutaj wh. Aplikacja będzie wdrożona na serwerze oepas1.

Serwis ABL będzie miał nazwę whsrv.

Projekt jest podłączony do bazy danych sports2000. Naciskamy Finish.

Projekt został utworzony. Teraz zdefiniujemy klasę Business Entity o nazwie customer.

Wybieramy tabelę Customer z bazy sports2000 oraz nazwę zasobu w URI: /customer.

Prawym klawiszem myszy klikamy na wygenerowany serwis i Edit. Zaznaczamy klasę customer.cls, która ma być źródłem dla serwisu. Naciskamy Finish.

Warto zaznaczyć, że dla serwisów typy WEB obok pliku .json jest wygenerowany plik .gen. Możemy to zauważyć w widoku konsoli.

Teraz pora na restart pasoe i sprawdzenie naszego serwisu. W przeglądarce (tutaj Firefox) wpisujemy localhost:[port]/wh/web/pdo/whsrv/customer

W adresie możemy skorzystać z filtra; chcemy np. tylko rekordy z Finlandii: localhost:[port]/wh/web/pdo/whsrv/customer?filter=Country=”Finland”

Proste, prawda?

Jakie są rekomendacje Progress Software dotyczące wyboru warstwy transportowej i metody budowania serwisów wg warstwy REST czy WEB.

REST – oparte na Javie, są rekomendowane przy wystawianiu istniejącej, restowej logiki biznesowej, gdy nie chcemy pisać kodu od początku.

WEB – oparte na języku ABL, o wiele bardziej skalowalne. Są rekomendowane jeśli chcemy pisać serwisy od zera.

PASOE i WebSpeed

Myślę, że wielu spośród polskich klientów Progressa pamięta czasy wersji 9 (koniec lat 90-tych), z którą wprowadzona została technologia tworzenia aplikacji webowych WebSpeed. Składał się on z dwóch produktów: WebSpeed Transaction Servera – odpowiedzialnego za uruchamianie i poprawność działania aplikacji, zapewniającego spójność transakcji i danych przy jednoczesnym korzystaniu z wielu baz. Drugim produktem był WebSpeed Workshop, złożone środowisko do tworzenia aplikacji.

Pamiętam, że technologia ta cieszyła się sporym zainteresowaniem naszych klientów, co zaowocowało kilkoma szkoleniami z tego zakresu. W wersji OpenEdge 10, WebSpeed został scalony z produktem OpenEdge AppServer. Po wprowadzeniu nowego serwera aplikacji PASOE i zaprzestaniu rozwijania klasycznego AppServera pojawiło się pytanie: co dalej z aplikacjami WebSpeed?

Zanim odpowiem na to pytanie chciałbym krótko przypomnieć w jaki sposób można było tworzyć aplikacje WebSpeed. Użytkownik miał do wyboru trzy możliwości.

Pierwszym był plik HTML, w którym można było osadzić elementy języka SpeedScript pomiędzy znacznikami <script language=”SpeedScript”> … </script>. SpeedScript, to był w zasadzie język 4GL z wyłączeniem operacji wejścia/wyjścia. Zamieszczam prosty przykład; operacje wyjścia kierowane są do predefiniowanego strumienia.

<HTML>
  <HEAD>
  </HEAD>
  <BODY>
    <H1> Customer List </H1>
    <SCRIPT LANGUAGE=”SpeedScript”>
      FOR EACH customer:
        DISPLAY {&WEBSTREAM} customer.
      END.
    </SCRIPT>
  </BODY>
</HTML>

Drugim sposobem było niejako odwrócenie ról; językiem nadrzędnym był SpeedScript a znaczniki HTML były osadzane w strumieniu {&OUT}, jak poniżej…

PROCEDURE ws-out:
{&OUT}
 „<HTML>”:U SKIP
 „<BODY>”:U SKIP
 .
  FOR EACH customer:
   {&DISPLAY} customer.
  END.
{&OUT}
 „</BODY>”:U SKIP
 „</HTML>”:U SKIP
 .
END PROCEDURE.

Wreszcie ostatnim sposobem, najbardziej rozbudowanym było mapowanie HTML. Tworzone były wówczas 2 pliki: HTML (zwykle forma z polami i przypisaną akcją) oraz plik .w.

Otóż, w nowym serwerze aplikacji można obsługiwać dwa pierwsze typy aplikacji. Jednakże, jeśli przypomnimy sobie 2 artykuły PASOE i serwisy WebHandler zobaczymy, że ta nowa technologia daje nam o wiele większe możliwości.

Sposób otwierania naszych aplikacji .w jest bardzo prosty.

Załóżmy, że mamy skonfigurowaną instancję serwera aplikacji, która połączona jest do bazy danych sports2000. Chcemy otworzyć plik w-custlist.w, będący prostą aplikacją WebSpeeda.

W katalogu roboczym naszej instancji przechodzimy do podkatalogu: %WRK%\instancja\webapps\ROOT\WEB-INF\openedge i umieszczamy tam plik .w. (oczywiście zamiast słowa ‘instancja’ umieszczamy nazwę naszego pasoe).

Następnie otwieramy plik %WRK%\instancja\conf\openedge.properties
i szukamy tam frazy: instancja.ROOT.WEB.defaultHandler.
Powinna mieć wartość: OpenEdge.Web.OpenEdge.Web.CompatibilityHandler.
Jeśli tak nie jest uruchamiamy komendę:
oeprop instancja.ROOT.WEB.defaultHandler=OpenEdge.Web.OpenEdge.Web.CompatibilityHandler
Wpis w pliku konfiguracyjnym będzie miał zatem postać:

[instancja.ROOT.WEB]
    defaultCookieDomain=
    wsRoot=/static/webspeed
    srvrDebug=1
    defaultHandler=OpenEdge.Web.CompatibilityHandler

Oczywiście możemy także wartości parametrów wpisywać ręcznie, ale łatwiej wtedy o pomyłkę. Zawsze najpierw warto zrobić kopię pliku konfiguracyjnego.

Restartujemy instancję serwera i wpisujemy w przeglądarce URL:

http://localhost:8810/web/w-custlist.w

Proszę zauważyć, że wykorzystywana jest czwarta warstwa komunikacji – WEB. Zaglądając do wspomnianych wcześniej 2 artykułów można spróbować zdefiniować klasy obsługujące różne wywołania dla odpowiednio podanych wartości URL.

Tworzenie obiektowego UI w OE Development Studio cz. IV

W czwartej części naszego cyklu, zajmiemy się obiecanym tematem edycji rekordów w bazie danych. Przypomnijmy: dane wyświetlane w obiektach graficznych są zasilane ze źródła BindingSource.
To źródło pobiera dane z tabeli np. Customer czy Order, ale działa niejako w jednym kierunku, tzn. nie nadaje się do zapisu danych. W naszych przykładach zapis będzie realizowany do tabel w bazie poprzez zdefiniowane statyczne bufory rekordów.

W przypadku aplikacji działającej np. na serwerze aplikacji, gdzie nie ma bezpośredniego dostępu do bazy, źródło BindingSource konfiguruje się w oparciu o schemat ProDataSet, z tabelami tymczasowymi, a edycja jest realizowana poprzez zapis do tych właśnie obiektów.

OK, zaczynamy.

W formie fCustomer dodajemy przycisk z etykietą Delete, nazwa np. Del.
Klikamy dwa razy w zdarzenie Click aby utworzyć metodę do obsługi tego zdarzenia (Del_Click). W metodzie tej wstawiamy poniższy kod:

DEFINE BUFFER bCust FOR Customer.
DEFINE BUFFER bOrder FOR Order.
DEFINE VARIABLE lDel AS LOGICAL NO-UNDO.
DEFINE VARIABLE iActCustNum AS INTEGER NO-UNDO.
		
MESSAGE "Do you want to delete this record?" SKIP 
            bsCust:InputValue["Name"]:ToString() SKIP 
	    bsCust:InputValue["City"]:ToString() SKIP
VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO UPDATE lDel.
IF NOT lDel THEN 
   RETURN.

Na razie mamy sukces tylko połowiczny – pojawia się komunikat gdzie możemy podjąć decyzję o kasowaniu rekordu.

Teraz dodamy kod kasujący rekord Customer i połączone z nim rekordy Order.
Dodajemy kod poniżej instrukcji RETURN:

IF NOT lDel THEN 
   RETURN.

iActCustNum = INTEGER(bsCust:InputValue["CustNum"]:ToString()).
DO TRANSACTION ON ERROR UNDO, RETURN:
   FOR FIRST bCust WHERE bCust.CustNum = iActCustNum:
      FOR EACH bOrder WHERE bOrder.CustNum = bCust.CustNum.
          DELETE bOrder.
      END.
      DELETE bCust.
   END. 
END. 

Żeby program zadziałał trzeba pamiętać, że w bazie są jeszcze trygery, zabezpieczające przed utratą danych. Trzeba albo te trygery zmodyfikować albo wyłączyć. Decyzja należy do Was.

Drugim problemem jest to, że po skasowaniu rekordu DataGrid nie odświeża automatycznie danych; musimy to zrobić sami.
Dodajemy w metodzie kod:

bsCust:MovePrevious().
iPos = bsCust:POSITION.
refreshData().
bsCust:POSITION = iPos.

Zmienną iPos deklarujemy jako integer. Po skasowaniu kursor ustawia się na poprzednim rekordzie.

Teraz dodajemy przyciski Edit i Create i generujemy metody dla zdarzenia Click.

Przeważnie te same funkcjonalności można stworzyć na różne sposoby. Można np. wykorzystać możliwości jakie daje DataGrid, ale wg Wiesława, ta metoda może generować wiele problemów i nie jest zbyt czytelna. Wygodniej jest stworzyć oddzielne okno dla edycji. Tworzymy więc nową formę fCustEdit.

Dodajemy 4 pola TextBox: CustNum, Name, City, Country, oraz etykiety dla tych pól.

Wstawiamy przyciski btnOK (etykieta OK), btnCancel (etykieta Cancel) i ustawiamy ich predefiniowaną funkcjonalność.

We właściwościach fCustEdit ustawiamy parametr CancelButton -> btnCancel.
We właściwościach btnOK ustawiamy DialogResult -> OK.

Wracamy do okna fCustomer, do metody dla kliknięcia przycisku Edit. Wstawiamy tu kod:

METHOD PRIVATE VOID Edit_Click( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
   DEFINE VARIABLE oCustEdit AS fCustEdit NO-UNDO.
   oCustEdit = NEW fCustEdit().
   WAIT-FOR oCustEdit:ShowDialog().
   DELETE OBJECT oCustEdit.

   RETURN.

Przycisk Edit już działa choć na razie nie widzimy danych.

Aby przekazać dane do edycji można skorzystać z różnych metod. My zdefiniujemy w fCustEdit właściwości dla każdego edytowanego pola. Np. pName dla pola Name; i tak dalej dla pozostałych pól.

    DEFINE PUBLIC PROPERTY pName AS CHARACTER NO-UNDO 
    GET.
    SET. 

Generujemy obsługę zdarzenia Shown dla fCustEdit i wpisujemu kod:

METHOD PRIVATE VOID fCustEdit_Shown( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
   ASSIGN
      textBoxName:TEXT = pName
      textBoxCity:TEXT = pCity
      textBoxCountry:TEXT = pCountry
      textBoxCustNum:TEXT = string(pCustNum).
   RETURN.

END METHOD.

Nasze okno edycyjne będzie pokazywać dane ustawione w fCustomer. Ponieważ pole CustNum nie może być przez nas edytowane ustawiamy w jego właściwościach Enabled = False, a żeby wyłączyć ramkę wokół pola ustawiamy BorderStyle = None.

Aby zapisać dane po edycji dodajemy obsługę kliknięcia na przycisk OK.

METHOD PRIVATE VOID btnOK_Click( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
   ASSIGN 
      pName    = textBoxName:Text
      pCity    = textBoxCity:Text
      pCountry = textBoxCountry:TEXT.
   RETURN.

END METHOD.

Wracamy do fCustomer i ustawiamy właściwości do wyświetlenia w oknie fCustEdit, czyli dodajemy kod w Edit_Click:

oCustEdit = NEW fCustEdit().
		   	
oCustEdit:pCustNum = int(bsCust:InputValue["CustNum"]:ToString()).
oCustEdit:pName = bsCust:InputValue["Name"]:ToString().
oCustEdit:pCity = bsCust:InputValue["City"]:ToString().
oCustEdit:pCountry = bsCust:InputValue["Country"]:ToString().
iActCustNum = INT(bsCust:InputValue["CustNum"]:ToString()).
		
WAIT-FOR oCustEdit:ShowDialog().

Okno fCustEdit wygląda teraz tak:

Następnym krokiem jest zapis wprowadzonych danych w fCustomer na dole obsługi Edit_Click. Dodajemy transakcję:

WAIT-FOR oCustEdit:ShowDialog().

DO TRANSACTION ON ERROR UNDO, RETURN:
   FOR FIRST bCust WHERE bCust.CustNum = iActCustNum SHARE-LOCK :
      ASSIGN
         bCust.Name    = oCustEdit:pName
         bCust.City    = oCustEdit:pCity
         bCust.Country = oCustEdit:pCountry.
   END.
END.

bsCust:Refresh().

OK, edycja jest już obsłużona. Pozostało jeszcze dodanie obsługi dla utworzenia nowego rekordu.

W tym celu wykorzystamy okno fCustEdit i fragment kodu dla edycji. Nie musimy przekazywać wartości pól, ale tworzymy nowy rekord komendą CREATE. Kod dla przycisku Create wygląda tak:

DEFINE BUFFER bCust FOR Customer.
DEFINE VARIABLE oCustEdit AS fCustEdit NO-UNDO.
DEFINE VARIABLE rRowid AS ROWID NO-UNDO.
        
oCustEdit = NEW fCustEdit().
                   
WAIT-FOR oCustEdit:ShowDialog().		
        
DO TRANSACTION ON ERROR UNDO, RETURN:
   CREATE bCust.
   ASSIGN
      bCust.Name    = oCustEdit:pName
      bCust.City    = oCustEdit:pCity
      bCust.Country = oCustEdit:pCountry.
   rRowid = ROWID(bCust).
END.

refreshData().
bsCust:HANDLE:reposition-to-rowid(rRowid).
RETURN.


Zmienna ROWID jest potrzebna żeby po dodaniu ustawić się na nowym rekordzie.
Małą niedogodnością wykorzystania formy fCustEdit jest to, że numer rekordu wynosi 0, ale z tym powinniście sobie poradzić bez problemu np. przenosząc instrukcję CREATE przed wywołanie formy i przekazanie parametru CustNum.


W zasadzie program jest gotowy, ale Wiesław chciał na koniec uatrakcyjnić go nieco dla Was.
Po pierwsze dodajmy klawisze skrótów dla operacji na rekordach.

We właściwościach formy fCustomer ustawiamy KeyPreview = True.

Następnie dla gridu włączamy zdarzenie KeyDown.

W metodzie obsługującej to zdarzenie definiujemy:

METHOD PRIVATE VOID dataGridView1_KeyDown( INPUT sender AS System.Object, INPUT e AS...
   CASE e:KEYCODE:ToString():
      WHEN "Insert" THEN Cre:PerformClick().
      WHEN "Return" THEN Edit:PerformClick().
      WHEN "Delete" THEN Del:PerformClick().
   END CASE.
   RETURN.

END METHOD.

Cre, Edit, Del to nazwy przycisków odpowiednio dla: Create, Edit i Delete. Całość działa poprawnie.

I już naprawdę na koniec, dodamy licznik rekordów. Przyda się gdy będziemy dodawać czy usuwać rekordy.
Dodajemy obiekt typu label, nadajemy nazwę np. labInfo. W metodzie refreshData dodajemy na końcu linię kodu:

labInfo:TEXT = "Liczba rekordów: " + STRING(bsCust:Count).

Po każdym wywołaniu tej metody liczba rekordów jest wyświetlana w obiekcie.

Niniejszym kończymy na razie cykl tworzenia aplikacji przy wykorzystaniu obiektów .Net w ABL, ale być może do niego wrócimy. Ponieważ pojawiła się już wersja OpenEdge 12, teraz trzeba napisać coś na ten temat.

Wiesław Kurzątkowski
Piotr Tucholski

Tworzenie obiektowego UI w OE Development Studio cz. III

W poprzedniej części zbudowaliśmy aplikację składającą się z dwóch okienek (form) z browserami danych z bazy OpenEdge. Wszystkie te dane są do odczytu; ich edycję omówimy niedługo, ale jeszcze nie w tym odcinku.

Na razie wracamy do ustawień, związanych z wyświetlaniem danych w DataGrid. Tych parametrów jest bardzo dużo. Omówimy tylko wybrane, zostawiając Wam pole do własnych badań.


W parametrach DatGridView formy fOrder, parametr: AutoSizeColumnsMode – ustawmy na wartość: Fill.


W oknie widzimy, że kolumny są ciasno upakowane. Ponieważ jednak to .Net i mamy odpowiednio ustawiony parametr Anchor więc po rozciągnięciu okna mamy widok:

Można te dane jeszcze bardziej ścieśnić ustawiając wartość: DisplayedCellsExceptHeader. Etykiety kolumn mogą jednak nie być wyświetlone w całości.

AutoSizeRowsMode – wpływa na automatyczne ustawienie wysokości wiersza. Przy pomocy tego parametru możemy np. wyświetlić łamane wartości pola.

Przechodzimy teraz do formy fCustomer. Dodajmy do DataGrid pole Comments. Ustawmy AutoSizeRowsMode na wartość DisplayedCells – wysokość wiersza będzie dobrana po analizie rekordów do wyświetlenia. Możemy ustawić również wartość AllCells, ale w przypadku dużej liczby rekordów analiza może trwać o wiele dłużej.


Wchodzimy do edytora kolumn: Zadania DataGridView -> Edytuj kolumny… (edytor jest także dostępny pod widokiem z właściwościami).

Zaznaczamy pole Comments. W sekcji Wygląd wybieramy parametr DefaultCellStyle: DataGridViewCellStyle …

Ustawmy WrapMode na True oraz jakiś kolor tła – parametr BackColor.

Pole Comments jest już wyświetlane z zawijaniem wierszy.

A teraz pokażemy jak dodać dodatkowe pole do wyświetlenia w DataGrid, którego nie ma w bazie danych, a które bazuje na wartościach innych pól; w Progress ABL było ono znane jako calculated field.
Ponownie wchodzimy do Zadania DataGridView, ale tym razem klikamy Dodaj kolumnę…
Dodatkowa kolumna będzie zawierać sklejone wartości pól City i Country. Zaznaczamy opcję Kolumna niezwiązana z danymi i wypełniamy jak na rysunku poniżej.

Klikamy Dodaj.
W edytorze kolumn ustawiamy nową kolumnę CityCountry zaraz za polem Country.

Na razie w nowym polu nie ma żadnych danych.

Musimy teraz włączyć tryb wirtualny (VirtualMode) – wskazuje on czy podano własne operacje zarządzania danymi dla DataGridView.
Teraz trzeba włączyć obsługę odpowiedniego zdarzenia. Wg Wiesława można to zrobić na kilka sposobów, jednakże dobrym wyborem, ze względu na wydajność, jest zdarzenie CellValueNeeded. Jest ono wywoływane tylko gdy wartość komórki jest potrzebna np. do wyświetlenia czy przekazania wartości.

W kodzie zostaje wstawiona metoda obsługująca to zdarzenie. Poprzez parametr e mamy dostęp do argumentów zdarzenia.
W kodzie metody dodajemy prosty kod, dla przetestowania, czy idziemy właściwą drogą: e:Value = “OK”.

METHOD PRIVATE VOID dataGridView1_CellValueNeeded( INPUT sender AS System.Object, INPUT e AS System.Windows.Forms.DataGridViewCellValueEventArgs ):
       e:Value = "OK".
       RETURN.
END METHOD.

Na razie wszystko idzie zgodnie z planem.

Musimy teraz znaleźć nazwy obu kolumn w DataGridView, które zawierają dane dla City i Country.

METHOD PRIVATE VOID dataGridView1_CellValueNeeded( INPUT sender AS System.Object, INPUT e AS System.Windows.Forms.DataGridViewCellValueEventArgs ):
       e:Value = dataGridView1:Rows[e:RowIndex]:Cells[2]:Value:ToString() + ", " +
       dataGridView1:Rows[e:RowIndex]:Cells[3]:Value:ToString()..
       RETURN.
END METHOD.

W powyższej instrukcji wartości kolumn pochodzą z trzeciej i czwartej kolumny w gridzie (liczone 0,1,2,3…).
Zmiana kolejności kolumn w gridzie spowoduje błędne wyświetlanie w naszej dodatkowej kolumnie dlatego lepiej jest wstawienie wartości kolumn po nazwie. W deklaracji zmiennych możemy znaleźć:

DEFINE PRIVATE VARIABLE cityDataGridViewTextBoxColumn AS System.Windows.Forms.DataGridViewTextBoxColumn NO-UNDO.
.....................
DEFINE PRIVATE VARIABLE countryDataGridViewTextBoxColumn AS System.Windows.Forms.DataGridViewTextBoxColumn NO-UNDO.

Obsługę zdarzenia możemy zatem zapisać następująco:

METHOD PRIVATE VOID dataGridView1_CellValueNeeded( INPUT sender AS System.Object, INPUT e AS System.Windows.Forms.DataGridViewCellValueEventArgs ):
   e:Value = dataGridView1:Rows[e:RowIndex]:Cells["cityDataGridViewTextBoxColumn"]:Value:ToString() + ", " +
   dataGridView1:Rows[e:RowIndex]:Cells["countryDataGridViewTextBoxColumn"]:Value:ToString().
   RETURN.
END METHOD.

W nowej kolumnie dane wyglądają, tak jak to sobie zaplanowaliśmy. teraz trzeba tylko wyłączyć kolumny City i Country.

W edytorze kolumn ustawiamy wartość parametru Visible na False.

Teraz jest OK.

Dziękujemy za uwagę.

Wiesław Kurzątkowski
Piotr Tucholski

Tworzenie obiektowego UI w OE Development Studio cz. II

Kontynuujemy budowę aplikacji rozpoczętą w pierwszej części.

Mamy formę fCustomer; teraz zbudujemy drugą formę fOrder, która będzie zawierała browser (grid) z rekordami Order dla danego Customera.

Postępujemy analogicznie jak w poprzedniej części: do nowej formy wstawiamy źródło danych binding source, zmieniamy nazwę na np. bsOrder. Definiujemy schemat dla bsOrder.

Wstawiamy DataGridView wybierając źródło danych bsOrder.

Ponieważ browser ma pokazywać tylko rekordy Order dla zadanej wartości pola CustNum (nr klienta) trzeba przekazać z nadrzędnego okna (formy) parametr. Można to zrobić np. definiując w fOrder właściwość iCustNum.

    DEFINE PUBLIC PROPERTY iCustNum AS INTEGER NO-UNDO 
    GET.
    SET.

Metoda refreshData będzie tutaj wyglądała nieco inaczej niż w fCustomer.

    METHOD PUBLIC VOID refreshData(  ):
        
        def var bsOrdQuery as handle no-undo.
        def var bsOrdString as char no-undo.
        create query bsOrdQuery.
        bsOrdQuery:ADD-BUFFER (buffer order:handle).
        bsOrdQuery:QUERY-PREPARE ("for each order where order.custnum = "
                                   + string(iCustNum) + " by custnum").
        bsOrdQuery:QUERY-OPEN ().
        bsOrder:handle = bsOrdQuery.
        RETURN.

    END METHOD.

Wywołanie refreshData wstawiamy do kodu programu zgodnie z sugestiami z poprzedniej części.

Na koniec dodajemy do formy przycisk btnClose z etykietą Close. Definiujemy metodę dla zdarzenia Click wstawiając jedną instrukcję:

    METHOD PRIVATE VOID btnClose_Click( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
        THIS-OBJECT:Close( ).
	RETURN.

    END METHOD.

Teraz przechodzimy do formy fCustomer. Wstawiamy deklarację zmiennej oOrd.

    DEF VAR oOrd AS fOrder. 

Definiujemy metodę dla zdarzenia Click przycisku btnOrders.

    
    METHOD PRIVATE VOID btnOrders_Click( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
        IF (NOT VALID-OBJECT(oOrd) OR oOrd:IsDisposed) THEN DO:
            oOrd = NEW fOrder().
            oOrd:iCustNum = bscust:InputValue["CustNum"].
            oOrd:RefreshData().
            oOrd:Show().	//okno niemodalne

        END.
	RETURN.

    END METHOD.

Metoda tworzy instancję obiektu fOrder (najpierw sprawdza czy obiekt nie jest już zainicjowany), następie ustawia właściwość iCustNum (czyli przekazuje parametr), otwiera zapytanie i wyświetla formę w postaci niemodalnej. Oznacza to, że użytkownik ma dostęp zarówno do formy fOrder jak i fCustomer.

Gdybyśmy chcieli uruchomić fOrder w postaci modalnej (dostęp do fCustomer będzie dopiero po zamknięciu fOrder) to zamiast instrukcji oOrd:Show() trzeba napisać: WAIT-FOR oOrd:ShowDialog().

Okno z zamówieniami otwiera się przykrywając częściowo okno z klientami. Można zdefiniować parametry okna tak aby otwierało się np. tuż obok. Aby to osiągnąć trzeba skorzystać z poniższej sztuczki Wiesława:

    oOrd:Location = new System.Drawing.Point(int(this-object:Location:X) + 
        this-object:Width,int(this-object:Location:Y)).
    oOrd:Height = this-object:Height.

Cały tryger ma teraz następującą postać:

METHOD PRIVATE VOID btnOrders_Click( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
    IF (NOT VALID-OBJECT(oOrd) OR oOrd:IsDisposed) THEN DO:
        oOrd = NEW fOrder().
        oOrd:iCustNum = bscust:InputValue["CustNum"].
        oOrd:RefreshData().
        oOrd:Show().	//okno niemodalne
        //WAIT-FOR oOrd:ShowDialog().	//okno modalne
        oOrd:Location = new System.Drawing.Point(int(this-object:Location:X) + 
           this-object:Width,int(this-object:Location:Y)).
        oOrd:Height = this-object:Height.
    END.
	RETURN.

END METHOD.

Efekt widać poniżej:

Naszą aplikację trzeba jeszcze trochę usprawnić. Ponieważ zdecydowaliśmy się na okno niemodalne, trzeba obsłużyć zmianę wyświetlanego rekordu w oknie fCustomer – powinna temu towarzyszyć zmiana wyświetlanych danych w oknie fOrder.
W widoku zdarzeń bsCust klikamy na zdarzenie PositionChanged (innym zdarzeniem, które warto wziąć pod uwagę jest CurrentChanged).

Do kodu programu zostanie wstawiona metoda obsługująca to zdarzenie. Musimy dodać do niej poniższy kod:

METHOD PRIVATE VOID bsCust_PositionChanged( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
    IF VALID-OBJECT(oOrd) THEN DO:
        IF oOrd:IsDisposed THEN  
           RETURN.                                                              
        oOrd:iCustNum = bscust:InputValue["CustNum"].
        oOrd:RefreshData().
    END.	
    RETURN.

END METHOD.

Możecie teraz sprawdzić, że jeśli okno fOrder jest otwarte, zmiana podświetlonego rekordu w oknie fCustomer powoduje wyświetlenie zamówień dla tego rekordu.

To oczywiście nie koniec. Wkrótce pojawi się następna część.

Wiesław Kurzątkowski
Piotr Tucholski

Tworzenie obiektowego UI w OE Development Studio cz. I

Nieco ponad 2 lata temu pokazałem jak zrobić pierwsze kroki na drodze tworzenia interfejsu graficznego z wykorzystaniem obiektów .Net w narzędziu OpenEdge Developer Studio.
Temat ten w rozmowach z Wami co jakiś czas powraca. Powodem jest najczęściej chęć wykonania interfejsu o lepszym wyglądzie i bardziej skalowalnego niż tradycyjny, niemłody już interfejs progressowy.

Do powrotu skłoniło mnie ostatecznie spotkanie z Wiesławem Kurzątkowskim – specjalistą od programowania z wykorzystaniem technik obiektowych firmy Novum. Wiesław obiecał pokazać niektóre stosowane przez siebie rozwiązania oraz służyć swoją wiedzą fachową w razie pytań i wątpliwości.

W dokumentacji OpenEdge można znaleźć ciekawe przykłady całych aplikacji, ale zwracacie uwagę na to, że po pierwsze: nie tworzy się ich od podstaw, a z półgotowych projektów, po drugie: opierają się na kontrolkach Infragistics, na które trzeba mieć dodatkową licencję. W naszych przykładach wykorzystamy ogólnodostępne kontrolki Microsoft oraz OpenEdge. Jeśli będzie zainteresowanie z Waszej strony to także pokażemy coś z kontrolkami Telerik.

OK, rozpoczynamy od powtórzenia stworzenia prostej aplikacji, opisanej we wspomnianym artykule, przedstawiającej browser (grid) z rekordami z tabeli Customer, a następnie dodamy drugie okno zawierające grid z rekordami Orders dla danego Customera.

W narzędziu OpenEdge Developer Studio 11.7 zakładamy nowy projekt o nazwie net1 typu klienckiego GUI for .NET.

Do projektu przyłączamy połączenie z serwerem bazy sports2000 (opisywane już wcześniej). Teraz tworzymy nową formę New -> ABL Form o nazwie fCustomer, naciskamy Finish.

Klasę formy można podglądać w postaci kodu ABL lub wizualnej (OE Visual Designer). Między trybami możemy się przełączać np. poprzez F9 / Shift + F9.

Do pustej formy przeciągamy z zestawu kontrolek OpenEdge: ProBindingSource. W widoku Properties zmieniamy nazwę domyślną na bsCust.

Następnie definiujemy schemat dla bsCust wybierając połączenie z bazą danych. Wybieramy tabelę Customer i kilka pól, jak na rysunku.

Teraz dodajemy kontrolkę DataGridView, wybierając źródło danych binding source bsCust i ew. ustawiając kolumny w żądanej kolejności.

W oknie wstawiamy dwa przyciski (Microsoft Button): btnOrders z etykietą Orders i btnClose z etykietą Close, jak na rysunku. Uruchomienie naszej aplikacji nie spowoduje jeszcze wyświetlenia danych Customer. Trzeba w tym celu napisać krótki fragment kodu.

Dodajemy metodę refreshData, która definiuje i otwiera zapytanie dla tabeli Customer, a następnie podpina je do źródła danych bsCust.

    METHOD PUBLIC VOID refreshData(  ):
        
        DEF VAR bsCustQuery AS HANDLE NO-UNDO.
        DEF VAR bsCustString AS CHAR NO-UNDO.
        CREATE QUERY bsCustQuery.
        bsCustQuery:ADD-BUFFER (BUFFER customer:HANDLE).
        bsCustQuery:QUERY-PREPARE ("FOR EACH customer").
        bsCustQuery:QUERY-OPEN ().
        bsCust:HANDLE = bsCustQuery.
        RETURN.

    END METHOD.

Wywołanie tej metody dodajemy do konstruktora.

    CONSTRUCTOR PUBLIC fCustomer (  ):
             
        SUPER().
        InitializeComponent().
        THIS-OBJECT:ComponentsCollection:ADD(THIS-OBJECT:components).
        refreshData().
        
        CATCH e AS Progress.Lang.Error:
            UNDO, THROW e.
        END CATCH.

    END CONSTRUCTOR.

Uruchamiamy aplikację – dane z tabeli Customer są poprawnie wyświetlane w browserze.

Wywołanie refreshData w konstruktorze może w niektórych przypadkach bardziej złożonych aplikacji być niekorzystne i generować błędy. To samo osiągniemy wstawiając wywołanie refreshData w metodzie formy Load lub Shown. Klikamy więc dwukrotnie w widoku Events na Shown; automatycznie jest wstawiona do naszego kodu metoda obsługi dla tego zdarzenia. Przenosimy tutaj wywołanie refreshData z konstruktora.

    METHOD PRIVATE VOID fCustomer_Shown( INPUT sender AS System.Object, INPUT e AS System.EventArgs ):
        refreshData().	
	RETURN.

    END METHOD.

W obiektach .NET jest wiele predefiniowanych ustawień i zdarzeń, które możemy wykorzystywać dla poprawienia funkcjonalności naszych aplikacji. Jednym z nich jest automatyczne sortowanie AutoSort dla binding source. Zmieniamy wartość tego parametru na True.


Jeśli klikniemy teraz na nazwę kolumny, uzyskamy sortowanie danych w browserze według jej wartości. Poniżej widać sortowanie po polu Name.

Na koniec tej części pokażemy ustawienia parametru Anchor (zakotwiczenie) i jak on wpływa na skalowalność obiektów.

Domyślna wartość Anchor to Top, Left. Wartości te powodują, że obiekt nie jest dobrze skalowalny gdy zmieniamy rozmiar okna pociągając za prawą lub dolną krawędź. Na obrazku poniżej, browser nie zwiększył automatycznie wysokości, a prawy przycisk jest niewidoczny.

Na tym rysunku poszerzenie okna nie powoduje zwiększenie szerokości browsera.

Zmieńmy ustawienia Anchor dla browsera na: Top, Bottom, Left, Right

… a dla przycisków na: Bottom, Right. Uruchamiamy znów aplikację…

Zmiana rozmiarów okna powoduje automatyczne dostosowanie rozmiaru browsera, a przyciski pozostają widoczne pod browserem.

Rozszerzenie okna powoduje wprawdzie odsłonięcie szarego obszaru, ale tylko dlatego, że nie ma więcej kolumn do wyświetlenia. Chyba fajnie, co?

Na razie to tyle. Następnym razem dodamy okno dla zamówień aktualnego klienta.

Wiesław Kurzątkowski
Piotr Tucholski

1 2 3 4 5