Im Zeitalter der mobilen Geräte brauchen wir Ihnen bestimmt keine Argumente mehr dafür zu liefern, dass Ihre Anwendungen in der Lage sein sollten, Web-Services zu benutzen oder zur Verfügung zu stellen. Die Frage ist nur, welche Tools für Sie am geeignetsten sind, um dies zu realisieren Eine Möglichkeit ist das IBM-Produkt Integrated Web Services for IBM i. An einem Beispiel zeigen wir Ihnen hier, wie Sie dieses Tool zur Erstellung integrierter Web-Services benutzen können, um einen vorhandenen Web-Service mit RPG zu verarbeiten.
In unserem Beispiel benutzen wir einen Web-Service, der für eine eingegebene Zahl die Ziffern als Text ausgibt, also für die Eingabe 1234 den Text „one thousend two hundred and thirty four“ zurückgibt und wahlweise das Wort Dollar hinzufügt. Einen solchen Web-Service könnten Sie in einer deutschen Version zum Beispiel beim Drucken von Schecks einsetzen. Hier zeigen wir Ihnen, wie Sie die RPG-Schnittstelle zu diesem Web-Service erstellen.
Genaue Hinweise dazu, was installiert sein muss, um das Beispiel auf Ihrem eigenen System nachzuvollziehen oder Ihre eigene Anwendungsentwicklung mit dem Tool „Integrated Web Services for IBM i“ vorzunehmen, finden Sie im „IBM i Web Services Client for ILE Programming Guide“.
Der gesamte Ablauf zum Erstellen des RPG-Programms, das diesen Web-Service verarbeitet, besteht aus den folgenden Schritten:
• Mit dem Tool „Web Services Description Language“ (WSDL), das im Integrated Web Services Client enthalten ist, sammeln Sie die Informationen aus der WSDL-Datei, die Sie zur Erstellung der RPG-Platzhalter-Programme (stubs) benötigen. Diese RPG-Platzhalter-Programme bilden später die Schnittstelle zwischen dem Web-Service und dem RPG-Programm.
• Das WSDL-Tool generiert eine Reihe von Dateien, die Ihnen als Schnittstelle zur Verfügung stehen.
• Schreiben und Testen Ihres RPG-Programms.
Lassen Sie uns jetzt die einzelnen Schritte genauer betrachten. Als Erstes benötigen Sie die WSDL-Datei, die den Web-Service beschreibt. Für unser Beispiel finden Sie ihn unter diesem Link:
http://www.dataaccess.com/webservicesserver/numberconversion.wso?WSDL
Es handelt sich hierbei um eine XML-Datei, die Sie über das Menü Ihres Browsers auf Ihre Workstation runterladen können. Stellen Sie sicher, dass Sie als Datei-Extension .wsdl angeben. Damit Sie nun mit der WSDL-Datei arbeiten können, müssen Sie diese in ein IFS-Datenverzeichnis kopieren. Das geht am einfachsten im Explorer für ferne Systeme in RD Power. Dort können Sie in der Sicht Ferne Systeme Ihre lokal gespeicherte .wsdl-Datei auswählen und in das gewünschte IFS-Verzeichnis kopieren. Wir benutzen in unserem Beispiel das Verzeichnis /home/weiss/numberconversion.wsdl.
Den ersten Verarbeitungsschritt führen Sie in QSHELL aus. Wenn Sie in Ihrem 5250-Emulator qsh eingeben, können Sie anschließend folgenden Befehl ausführen:
/QIBM/ProdData/OS/WebServices/V1/client/bin/wsdl2ws.sh-o/myWSLabxx/RPG -lrpg -ms256 -ma5-s/qsys.lib/RSELABXX.lib/wsrpg.srvpgm/home/weiss/numberconversion.wsdl
Der Befehl wsdl2ws.sh startet das Tool, das die Web-Service-Schnittstelle generiert. Standardmäßig ist dieser Befehl im Verzeichnis /QIBM/ProdData/OS/WebServices/V1/client/bin installiert. Der Rest des Befehls setzt folgende Parameter:
-o: das Ausgabeverzeichnis für die Quellendateien auf /myWSLabxx/RPG
-l: die Zielsprache, die hier generiert werden soll auf rpg
-s: den Pfad zum Serviceprogramm und den Namen des Serviceprogramms, das generiert werden soll auf /qsys.lib/RSELABXX.lib/wsrpg.srvpgm
-ms: maximale Länge für RPG-Character-Felder
-ma: maximale Größe für RPG Arrays
Der letzte Parameter, /home/weiss/numberconversion.wsdl, spezifiziert Namen und Pfad zur WSDL-Datei.
Es gibt noch weitere Parameter. Diese entnehmen Sie bitte dem Web Services Programming Guide.
Abbildung 1: Befehl und erfolgreiche Ausführung
Nach erfolgreicher Generierung enthält der Root-file-system-Knoten das angegebene Verzeichnis, in unserem Fall myWSLabxx/RPG, und darin eine Anzahl von neuen Quellendateien. Wir sind für unser Beispiel nur an der Datei NumberConversionSoapType.rpgleinc interessiert.
Abbildung 2: Die generierten Dateien im IFS
Sie haben zwei Möglichkeiten, mit diesen Dateien weiterzuarbeiten, Sie können sie im IFS lassen oder in die passenden Quellendateien Ihrer Bibliothek kopieren und von da aus arbeiten. In beiden Fällen können Sie dafür den Explorer für ferne Systeme in RD Power benutzen.
Zusätzlich zu den Dateien im IFS enthält die im Generierungsbefehl angegebene Bibliothek – in diesem Fall RSELABXX – drei neue Module und ein Serviceprogramm:
Abbildung 3: Die generierten Objekte in der Bibliothek
Die im IFS generierten Dateien vom Typ .rpgle und .c sind die Quellen für diese Module. Während der Befehl wsdl2ws ausgeführt wird, werden die Modulobjekte und das Serviceprogramm, das aus diesen Modulen besteht, von einem CL-Programm erzeugt. Das CL-Programm wird ebenfalls automatisch erstellt. Der Quellencode des CL-Programms befindet sich in der Datei NumberConversionSoapType.cl. Wenn Sie dieses Programm laufen lassen wollen, müssen Sie es erst neu kompilieren.
Die Datei NumberConversionSoapType.rpgleinc benötigen Sie für Ihr RPG-Programm, das den Web-Service verarbeiten soll. Dieses Programm muss die Datei mit einer /copy-Anweisung einschließen. Wenn Sie mit der /copy-Anweisung direkt auf die Datei im IFS hinweisen wollen, müssen Sie das Format /COPY /dir1/dir2/file verwenden, also:
/copy /myWSLabxx/RPG/NumberConversionSoapType.rpgleinc
Wenn Sie lieber mit einer Quellendatei in einer Bibliothek arbeiten, können Sie natürlich die Datei auch aus dem IFS kopieren und dann die entsprechende /copy-Anweisung verwenden.
Unsere Benutzerschnittstelle für den Aufruf des Web-Service besteht aus einem einfachen Screen, der die Eingabe der Ziffern erlaubt und „Y“ oder „N“, je nachdem, ob der ausgeschriebenen Zahl das Wort Dollar hinzugefügt werden soll oder nicht. Die dazugehörige DDS-Datei nennen wir DISPLAY.
Abbildung 4: Benutzerschnittstelle des RPG-Programms
Das RPG-Programm enthält neben der Dateidefinition, der /copy-Anweisung und den Definitionen für die Ein- und Ausgabefelder eine Datenstruktur, die die Einzelheiten des Web-Service speichert. In der Web-Services-Dokumentation wird sie auch Stub genannt.
d WsStub ds likeds(This_t)
Die Variable WsStub.endpoint definiert, wo sich der Web-Service befindet. Wenn der Wert „Blank“ ist, wird die Information aus der WSDL-Datei genommen.
Die Anweisung stub_create_NumberConversionSoapType(WsStub) legt fest, dass der WsStub auf den Web-Service „NumberConversion“ zeigt.
Die Anweisung stub_op_NumberToDollars(WsStub:Input1:Result) ruft die Funktion „NumberToDollars“ im Web-Service „NumberConversion“ auf. Der erste Parameter zeigt auf den Web-Service, die weiteren Parameter sind die Ein- und Ausgabeparameter des Web-Service, also die Zahl, die zum Service geschickt wird und der Text, der zurückgegeben wird.
Die Anweisung stub_op_NumberToWords(WsStub:Input2:Result) ruft die Funktion „NumberToWords“ im gleichen Web-Service auf. Beachten Sie, dass die Variablen INPUT1, INPUT2 und RESULT die Datentypen des Web-Service reflektieren. Sie brauchen sich um Datenkonversionen nicht zu kümmern.
Die Anweisung stub_destroy_NumberConversionSoapType(WsStub) gibt den Speicherplatz, der von der Stub-Datenstruktur eingenommen wurde, wieder frei.
Alle Web-Service-Funktionen sind boolean, die „wahr“ zurückgeben, wenn die Funktion erfolgreich ausgeführt wurde. Andernfalls enthält die Variable WsStub.exc die Fehlermeldungen des Web-Service.
Das vollständige RPG-Programm finden Sie am Ende des Artikels.
Um das Modul für das Programm zu erstellen, benötigen Sie den folgenden CRTRPGMOD-Befehl:
CRTRPGMOD MODULE(RSELABXX/NUMCONSOAP) SRCFILE(RSELABXX/QRPGLESRC) SRCMBR(NUMCONSOAP) REPLACE(*YES) OPTION(*EVENTF) DBGVIEW(*SOURCE)
Um das Programm zu erstellen, benutzen Sie den CRTPGM-Befehl, in dem das für diesen Web-Service generierte Serviceprogramm WSRPG sowie das Serviceprogramm QAXIS10CC eingebunden werden:
CRTPGM PGM(RSELABXX/NUMCONSOAP)BNDSRVPGM((QSYSDIR/QAXIS10CC) (RSELABXX/WSRPG))
Probieren Sie es doch mal aus. Das Tool „Integrated Web Services for IBM i“ erweitert Ihre Möglichkeiten zur Anwendungsentwicklung mit RPG. Mit diesem Tool können Sie – ohne andere Programmiersprachen erlernen zu müssen – mit den verschiedensten Anwendungen auch außerhalb des Systems IBM i kommunizieren.
Wir haben Ihnen hier gezeigt, wie Sie einen RPG Web-Service-Client erstellen, also einen bestehenden Web-Service konsumieren. Mit den Integrated Web Services for IBM i Tools können Sie auch einen RPG Web-Service erstellen, der als Server dient und somit von anderen konsumiert werden kann.
Viel Spaß beim Ausprobieren.
RPG-Quelle
* Quelle: NUMCONSOAP
* Sample RPGIV program to invoke a WebService using
* the AXIS client
* Created by Claus Weiss
*
* F spec fuer Datei-Display, wo Sie die Ziffern eingeben.
* Datei-Display enthaelt nur einen einfachen Screen.
* Input1 ist die eingegebene Zahl.
* Dies wird an den Web-Service geschickt.
* Der Web-Service schickt einen String zurueck,
* der den Text fuer die Ziffern enthaelt.
* Die Daten werden auf dem Screen angezeigt.
****************************************************************
FDISPLAY CF E WORKSTN
F
D* Strukturen und Konstanten aus der generierten .rpgleinc-Quellendatei
/copy /myWSLabxx/RPG/NumberConversionSoapType.rpgleinc d* Diese Variable enthaelt den zuruckgereichten String.
d OutputText s 60
d* Der Stub ist ein Pointer auf diese Instance des Web-Service.
d WsStub ds likeds(This_t)
d*Eingabe fuer den Web-Service
d Input1 ds likeds(xsd_decimal)
d Input2 ds likeds(xsd_unsignedLong)
d*Ausgabe des Web-Service
d Result ds likeds(xsd_string) D**************************************************************************
// Diesen Teil koennten Sie auch im festen Format mit EVAL schreiben. /FREE
// Schleife, um den Screen anzuzeigen bis F3 das Programm beendet.
dollarc = ‚Y‘;
DOW NOT *IN03;
EXFMT PRODREC;
// Initialisierung der Felder fuer eine neue Anfrage.
msg = “;
result = “;
// AXIS muss wissen wo sich der Web-Service befindet.
// Blank heisst, die Info ist im WDSL gespeichert.
WsStub.endpoint = ‚ ‚;
Monitor;
// *****************************************************
// Stub Interface-Funktion, um auf unseren Web-Service zu zeigen.
// *ON, wenn erfolgreich
// Parameter ist WsStub.
if (stub_create_NumberConversionSoapType(WsStub));
// Wir haben zwei Web-Service-Funktionen.
// Hier pruefen wir, welche Funktion der Benutzer ausfuehren will.
If dollarc = ‚Y‘ or dollarc = ‚y‘ ;
// mapping RPG- und Webservice-Datentypen
Input1.value = %float(NUMBERIN) ;
// NumberToDollars Web-Service aufrufen.
// Parameter sind Stub, Input und Rueckgabe vom Web-Service.
// *ON, wenn erfolgreich
if ( stub_op_NumberToDollars(WsStub:Input1:Result));
OutputText = Result.value;
else;
OutputText = WsStub.excString;
endif;
else;
// zweiter Web-Service
Input2.value = %float(NUMBERIN) ;
// NumberToWords Web-Service aufrufen.
if ( stub_op_NumberToWords(WsStub:Input2:Result));
OutputText = Result.value;
else;
OutputText = WsStub.excString;
endif;
endif;
// Ausgabe des Texts vom Web-Service
name = OutputText;
endif; On-Error;
msg = ‚getProductInfo error‘;
Endmon;
// Clean up
stub_destroy_NumberConversionSoapType(WsStub);
// Bildschirmausgabe und Warten auf naechste Eingabe
Enddo;
*inlr = *on;
/END-FREEDDS Quelle
A DSPSIZ(24 80 *DS3)
A CA03(03)
A R PRODREC
A*%%TS SD 20060303 162904 NTAJI REL-V5R4M0 5722-WDS
A 2 16’Number Conversion‘
A COLOR(WHT)
A 4 6’Convert numeric to a word‘
A 7 10’Enter number:‘
A COLOR(WHT)
A NUMBERIN 9 B 7 29
A 9 6’Got the word‘
A NAME 60A O 9 20
A MSG 30 O 15 10COLOR(RED)
A 5 10’Convert to dollar ? Y/N ‚
A COLOR(WHT)
A DOLLARC 1 B 5 36