REST Server mit RPG und IceBreak

Transkript

1 REST Server mit RPG und IceBreak ( 2018 Markus A. Litters) Inhaltsverzeichnis 1. Voraussetzungen REST Service generieren Der erste RPG REST Service chainrest.rpgle Service testen Teil Der zweite RPG REST Service jsonrest.rpgle Der dritte RPG REST Service DSPF2Rest.rpgle Fazit Seite 1/13

2 1. Voraussetzungen Wie in jedem meiner Folgetutorials wird eine lauffähige Version von IceBreak auf einem IBM i Server vorausgesetzt. Wie Sie dies durchführen können, erfahren Sie in meinem Tutorial Erste Schritte mit IceBreak, welches Sie auf der Seite: zusammen mit einigen anderen Tutorials finden. Zusätzlich benötigen Sie einen Editor, mit dem Sie den RPG Code erfassen können. Wir empfehlen das kostenlose Tool Visual Studio Code von Microsoft, welches unter Windows, Linux und Mac OS X läuft und über eine kostenlose RPG Erweiterung von Niels Liisberg, dem Schöpfer von IceBreak verfügt. Genaueres finden Sie in meinem Tutorial Visual Studio Code mit RPG und IceBreak auf der o.g. Webseite. Alle Beispielprogramme, die ich in diesem Tutorial behandle finden Sie in meinem IceBreak Repository unter GitHub: Dort finden Sie auch eine stetig wachsende Anzahl weiterer Beispiele und dürfen sich auch gerne selbst beteiligen und eigene Beispielprogramme einbringen. Wenn Ihnen die Beispiele gefallen, würde ich mich sehr darüber freuen, wenn Sie mir auf GitHub einen Stern schenken und das Repository mit der Watch Funktion beobachten, so dass Sie keine Neuen Beispiele verpassen. Seite 2/13

3 2. REST Service generieren In meinem Tutorial Web Anwendung und REST Service in unter 5 Minuten erfahren Sie, wie Sie mittels IceBreak Assistenten ganz einfach und in kurzer Zeit eine Web Anwendung inkl. vollständigem CRUD (Create, Read, Update und Delete) REST Service generieren können. Dies reicht in vielen Fällen aus, um einen REST Service zu erzeugen, der danach ggf. noch angepasst werden kann. Probieren Sie es einfach aus. Seite 3/13

4 3. Der erste RPG REST Service chainrest.rpgle Den vollständigen Quellcode zu folgendem Beispiel finden Sie unter GitHub: Wenngleich es sich bei unserem ersten Beispiel fast nicht lohnt den Quellcode noch einmal zu verlinken, denn er ist extrem überschaubar. <% Fproduct IF E K DISK /free Zunächst definieren wir ganz klassische mittels Native I/O eine Tabelle. In dem Fall die IceBreak Beispieltabelle PRODUCT, die sich in der Bibliothek ICEBREAK befindet. Danach schalten wir in den Free RPG Mode um und definieren die Ausgabe, die wir an den Client, der unseren Service aufruft, zurück senden setcontenttype('application/json;charset=utf-8'); REST Services müssen zwar nicht zwangsläufig Daten im JSON Format austauschen, sondern können auch in beliebigen anderen Formaten, wie XML oder auch CSV miteinander kommunizieren. In der Praxis finden Sie jedoch kaum einen REST Service, der nicht via JSON kommuniziert. Deshalb legen wir hier das Format auf JSON und den verwendeten Zeichensatz auf UTF-8. Diesen REST Service rufen Sie einfach wie folgt auf: Hierbei tragen Sie natürlich die IP / DNS Ihrer IBM i, sowie die Portnummer Ihrer IceBreak Instanz ein, die Sie für den REST Service verwenden. Der Parameter prodkey dient dazu, dass Sie sich die Daten für einen bestimmten Artikel holen können und wird wie folgt ausgelesen: prodkey = reqnum('prodkey'); Damit können wir auch schon einen klassischen CHAIN auf die Tabelle PRODUCT durchführen und prüfen, ob er erfolgreich war: chain prodkey productr; if not %found; %>{ "sucess" : false }<% Seite 4/13

5 War er nicht erfolgreich, geben wir dem Client als JSON Dokument { success : false } zurück, womit er weiß, dass er eine falsche Produkt ID übergeben hat. Im Erfolgsfall geben wir ein paar Produktdaten zurück, wobei diese in diesem Beispiel ganz einfach als RPG String zusammengebaut werden. IceBreak verfügt auch über mächtige JSON Funktionen, mit denen Sie komplexe JSON Dokumente sehr einfach in Ihrem RPG erstellen können, wie Sie in einem späteren Beispiel noch sehen werden: else; %>{ "sucess" : true, "prodkey" : <%= %char(prodkey) %>, "prodid" : "<%= prodid %>", "desc" : "<%= desc %>", "manuid" : "<%= manuid %>", "price" : <%= %char(price) %>, "stockcnt" : <%= %char(stockcnt)%>, "stockdate" : "<%= %char(stockdate) %>" }<% endif; Das war es auch schon. Mit diesem Service können Sie bereits jede beliebigen Web- oder mobile App bedienen und den Service natürlich ausbauen. D.h. Sie könnten oben Abfragen, wenn kein prodkey übergeben wird, dass Sie alle Artikel zurück liefern oder mehrere Parameter empfangen, um z.b. nur Artikel mit einer bestimmten Beschreibung zu lesen und und und. Seite 5/13

6 4. Service testen Teil 1 Wenn ich die Aufgabe erhalte einen neuen REST Service zu entwickeln, dann teste ich diesen immer zuerst mit einem allgemeinen Tool. Damit kann ich sicherstellen, dass mein REST Service auch wirklich so funktioniert, wie erwartet und das nicht der Client irgendein Problem hat. Zum Testen von REST Services gibt es jede Menge Tools, wobei die meisten davon kostenlos sind. Es gibt z.b. Browser Erweiterungen für Chrome, wie POSTMAN. Ich persönlich verwende meistens jedoch das Tool SoapUI. Dieses Tool gibt es ebenfalls als kostenlose Version, die für die meisten Tests vollkommen ausreicht. SoapUI hat verschiedene Vorteile, wie z.b. die Möglichkeit damit REST und SOAP Webservices zu testen, sowie Lasttests zu erstellen. Damit kann man u.a. prüfen, ob die Performance auch dann in Ordnung ist, wenn mehrere dutzend, hundert oder tausend User gleichzeitig zugreifen. Für unseren ersten, einfachen CHAIN Service, können Sie aber auch direkt im Browser die o.g. URL aufrufen und sollten dort dieses Ergebnis erhalten: Seite 6/13

7 5. Der zweite RPG REST Service jsonrest.rpgle Den vollständigen Quellcode zu folgendem Beispiel finden Sie unter GitHub: In diesem Beispiel, sehen Sie die Mächtigkeit von noxdb (not only XML), welches in IceBreak integriert ist. Greifen Sie per SQL auf die DB2 zu und erhalten reines JSON, welches Sie dann in RPG verarbeiten! Die Funktionsweise ist ähnlich der von embedded SQL. Zuerst definieren wir ein paar Variablen, wobei die wichtigsten prow und sqlhnd darstellen. Erschrecken Sie bitte nicht, weil es sich dabei um Pointer, also Zeiger auf Speicheradressen handelt. IceBreak nimmt Ihnen das gesamte Handling mit Pointern ab, benötigt diese jedoch, weil damit nicht nur schnelleres und flexibleres Arbeiten möglich ist, sondern auch die RPG Speicherbegrenzungen für Variablen umgangen werden können. Die anderen Variablen dienen rein dem Entgegennehmen der Daten aus dem JSON Dokument, welches wir gleich erzeugen. Als erste Anweisung geben wir wieder an, dass wir JSON Daten im UTF-8 Zeichensatz an den Client zurück liefern wollen: setcontenttype('application/json;charset=utf-8'); Nun initialisieren wir unseren SQL Handler sqlhnd mit der IceBreak Funktion json_sqlopen welche einen beliebigen DB2 SQL Befehl entgegen nimmt. sqlhnd = json_sqlopen( 'Select * from product' ); Json_sqlOpen liefert ein dynamisches Resultset im JSON Format zurück. D.h. wenn Sie über diesen Weg künftig z.b. auch intern in normalen RPG Programmen arbeiten, brauchen Sie sich keine Gedanken mehr darüber zu machen, ob die Tabelle geändert wurde oder nicht (es sei denn, Sie verwenden die Felder, die sich geändert haben an anderer Stelle im Programm ). Seite 7/13

8 Wenn es beim Initialisieren ein Problem gab, geben wir dies an den Client zurück if json_error(sqlhnd); msg = json_message(sqlhnd); %>Error: <% = msg %><% json_sqldisconnect(); return; // You can return, however the rest of the routines a roubust enough to just continue endif; ACHTUNG: In diesem Beispiel gebe ich einfach nur Text aus, der an den Client zurück geschickt wird, da wir zum ausprobieren i.d.r. den Browser verwenden. In einem produktiven REST Service geben Sie an der Stelle ebenfalls ein JSON Dokument zurück, in welches Sie z.b. die Fehlermeldung packen können. Das Beispiel zeigt jedoch auch, dass Sie innerhalb von IceBreak RPG beliebige Ausgabeformen mischen können. Nun holen wir uns den ersten Datensatz (oder das erste Vorkommen eines JSON Objekts), der in unser Resultset zurückgeschrieben wurde: prow = json_sqlfetchnext(sqlhnd); Diese Funktion füllt unsere Pointer Variable prow nun mit dem JSON Objekt, welches den nächsten Datensatz darstellt. In einer Do While Schleife, verarbeiten wir nun alle JSON Objekte (Datensätze), die im Resultset angekommen sind und geben diese auf dem Browser aus: dow (prow <> *NULL ); ints = json_getnum (prow : 'PRODKEY'); text = json_getstr (prow : 'PRODID'); %>ProdId: <% = text %> <% numbers = json_getnum (prow : 'PRICE'); %>Price: <% = %char(numbers) %> <% Auszugsweise habe ich hier ein Text-, sowie ein numerisches Feld dargestellt. Die IceBreak Funktionen json_getnum (get Number hol einen numerischen Wert) und json_getstr (get String hol einen alphanumerischen Wert) werden dabei angewandt, um innerhalb des JSON Objekts zu navigieren und die Daten auszulesen. Als ersten Parameter geben Sie das JSON Objekt an und als zweiten, den Schlüssel (Feldnamen), den Sie auslesen möchten. Seite 8/13

9 Nach erfolgreicher Ausgabe, müssen wir das JSON Objekt noch löschen, damit es zu keinen Überschneidungen im Speicher kommt und können den nächsten Datensatz lesen: json_nodedelete(prow); prow = json_sqlfetchnext(sqlhnd); Zu guter Letzt schließen wir noch unseren SQL Handler und trennen die Verbindung zur Datenbanke: json_sqlclose(sqlhnd); json_sqldisconnect(); Diese Aufrufe sind sehr wichtig, da sie den Speicher wieder frei geben, den IceBreak mit seinen Pointer Funktionen reserviert hat. Hat alles funktioniert und Sie haben das Programm erfolgreich umgewandelt, sollten Sie im Browser folgendes eingeben: (Bitte denken Sie an Ihre eigene IP und die richtige Portnummer) und folgende Ausgabe erhalten: Seite 9/13

10 6. Der dritte RPG REST Service DSPF2Rest.rpgle Den vollständigen Quellcode zu folgendem Beispiel finden Sie unter GitHub: In diesem Beispiel sehen Sie die Mächtigkeit des virtuellen 5250 Emulators, den wir direkt in RPG / Cobol nutzen können. Damit können Sie REST Services direkt aus Ihren 5250 Dialog Anwendungen erstellen und Ihre bewährte und stabile Geschäftslogik weiterverwenden! Sie simulieren einfach in RPG oder Cobol einen Anwender, der die Anwendung bedient und schreiben Daten in Felder, drücken beliebige Funktionstasten und lesen die Ergebnisse am Bildschirm aus! Das Beispiel nutzt den WRKSYSSTS Screen. Sie können jedoch JEDEN Screen verwenden, der auf Ihrem System läuft. Sie brauchen auch keinen Quellcode von dem verwendeten Programm! Natürlich weiß ich, dass man die Informationen aus WRKSYSSTS mittlerweile auch einfach als SQL View SYSTEM_STATUS_INFO abrufen kann dieses Beispiel soll lediglich anhand einer allgemeinen Anzeige, die auf jedem IBM i Server vorhanden ist, verdeutlichen, wie einfach man 5250 Anwendungen mit IceBreak automatisiert bedienen kann! Nachdem wir die Ausgabe wieder auf JSON und UTF-8 gesetzt haben, prüfen wir zunächst, ob wir bereits ein virtuelles 5250 Terminal geöffnet haben und falls nicht, öffnen wir einen: if (pvts = *null); pvts = vtopen(); endif; pvts ist dabei wieder eine Pointer Variable, aber wie schon im vorherigen Besipiel, brauchen Sie sich auch hier wieder nicht darum zu kümmern, denn die IceBreak Funktion vtopen übernimmt das für Sie. Seite 10/13

11 In einer Schleife prüfen wir nun so lange, bis wir in dem Screen sind, den wir tatsächlich erreichen möchten. Sind wir in einem anderen Screen, müssen entsprechende Aktionen durchgeführt werden. So müssen wir uns als erstes im Anmeldebildschirm anmelden: when vtsaatitlecontains(pvts:'anmelden'); vtsetfieldno(pvts: 1 : 'USER'); // First field is the userprofile vtsetfieldno(pvts: 2 : 'PASSWORD'); // Second field is the password vtsetfieldno(pvts: 3 : 'QCMD'); // Program to run - QCMD vtpresskey(pvts: vtenter); Die IceBreak Funktion vtsaatitlecontains prüft dabei, ob in der obersten Zeile (gemäß IBM SAA Richtlinien sollte dort die Überschrift stehen) der Text Anmelden vor kommt und wenn ja, schreiben wir in das erste Feld den Benutzernamen, in das zweite Feld das Kennwort und in das dritte Feld QCMD, weil wir einen Befehl ausführen wollen und drücken danach die Enter / Datenfreigabe Taste. Achten Sie bitte immer darauf, dass der Benutzer, den Sie im virtuellen Terminal verwenden auch tatsächlich die erforderlichen Berechtigungen besitzt, um die von Ihnen gewünschte Anwendung aufzurufen. Sollte der Benutzer schon irgendwo angemeldet sein, drücken wir einfach nur die Enter Taste, damit der angezeigte Screen übersprungen wird: when vtsaatitlecontains(pvts:'programmnachrichten anzeigen'); vtpresskey(pvts: vtenter); Die Schleife läuft dann erneut durch und prüft, ob wir nun in der Befehlseingabe sind. Wenn ja, wird der Befehl wrksyssts eingegeben und Enter gedrückt: when vtsaatitlecontains(pvts:'befehlseingabe'); vtsetfieldno(pvts: 1 : 'wrksyssts'); vtpresskey(pvts: vtenter); Im nächsten Durchgang sollten wir unser Ziel erreicht haben: when vtsaatitlecontains(pvts:'mit Systemstatus arbeiten'); vtpresskey(pvts: vtf10); PanelFound = *ON; Sicherheitshalber drücken wir noch die Funktionstaste F10 und teilen der Schleife mit, dass wir raus wollen. Sollten wir in irgendeinen anderen Screen versehentlich gerutscht sein, geben wir als JSON Objekt ein { ok : false } zurück: other; //!! TODO - invalid screen %>{ "ok": false}<% return; Seite 11/13

12 Jetzt, da wir im WRKSYSSTS sind und F10 gedrückt haben, wollen wir uns ein paar Daten vom Bildschirm holen: cpuused = num(vtgetscreen(pvts: 3: 33 : 6 ): decp); sysaspsize = num(vtgetscreen(pvts: 4: 70 : 8 ): decp); sysaspused = num(vtgetscreen(pvts: 5: 70 : 10 ): decp); Die IceBreak Funktion vtgetscreen ist fast selbsterklärend. Wir geben unser virtuelles Terminal Objekt (pvts) an, dann die Zeile und die Spalte, in welcher wir Daten abgreifen möchten und die Länge der Daten, die wir uns in eine RPG Variable speichern möchten fertig. Neben dieser recht simplen Methode gibt es noch weitere IceBreak Funktionen, die uns erlauben auch Inhalte aus Feldern zu holen, so dass die genaue Position des Feldes und seine Länge nicht bekannt sein muss. Zu guter Letzt geben wir die soeben geholten Informationen als JSON Dokument an den aufrufenden Client zurück: %>{ "cpuused" : <% = %char(cpuused) %>, "sysaspsize" : <% = %char(sysaspsize) %>, "sysaspused" : <% = %char(sysaspused) %> }<% Wenn Sie im Browser: aufrufen, sollte dieses Ergebnis (oder so ähnlich) zu sehen sein: In meinem Video Tutorial zu diesem Thema zeige ich das Ganze auch noch einmal mit einer richtigen Anwendung. Schaue Sie einfach mal rein! Seite 12/13

13 7. Fazit Wie Sie in dieser Anleitung gesehen haben, ist es sehr einfach mit IceBreak REST Services zu erstellen. Haben Sie sich erst einmal mit Webservices generell vertraut gemacht, ist die Benutzung oder Bereitstellung dieser mit IceBreak kein Problem. Durch die komfortablen Zusatzfunktionen, können Sie problems JSON (oder XML) Daten erstellen bzw. verarbeiten. Genauso hilft Ihnen IceBreak dabei mit dem IFS oder Large Objects innerhalb von IBM i zu arbeiten. Besonders hervorheben muss man die Möglichkeit, mit dem virtuellen 5250 Terminal Dialog Anwendungen automatisiert steuern zu können. Dabei kann man nicht nur REST oder SOAP Services daraus generieren, sondern jegliche Automatisierung durchführen! Alle Beispiele, die ich Ihnen in dieser und den anderen Dokumentationen zeige sind in der Programmiersprache RPG verfasst. Sollten Sie Beispiele in Cobol oder C/C++ benötigen, geben Sie mir bitte Bescheid und ich sende Ihnen solche zu. Seite 13/13