Prüflisten verwalten mit HTML und RPG-CGI

11. November 2008 | Von admin | Kategorie: Programmierung

Ein Internet-Artikel aus der NEWSolutions mit NEWSabo plus Zugang über: Prüflisten verwalten mit HTML und RPG-CGI – Eine moderne Schnittstelle löst ein altes RPG-Problem – Ein neues Werkzeug für Prüflisten

Read Offline:

Download PDF

Download ePub

Künstler Burgy Zapp

von Jan Jorgensen

Prüflisten (Objekttyp *VLD) sind seit V4R1 implementiert und dienen dazu, sicherheitskritische Benutzerinformationen zu speichern. Ein Prüflisteneintrag besteht aus einer Kennzeichnung, die verschlüsselt gespeichert wird, und aus dazugehörigen Daten in freiem Format. Zur Prüfung eines Eintrags muss der Benutzer sowohl die Kennzeichnung als auch die Daten eingeben. Ähnlich wie Benutzerbereiche können auch Prüflisten nur mit Hilfe von APIs verarbeitet werden. OS/400 bietet nur zwei Befehle, die mit Prüflisten zu tun haben: CRTVLDL (Create Validation List – Prüfliste erstellen) und DLTVLDL (Delete Validation List – Prüfliste löschen).

Mit Hilfe der Prüflisten-APIs können Prüflisteneinträge hinzugefügt, geändert, entfernt, gesucht und geprüft werden. Eine denkbare Verwendung von Prüflisten ist das Speichern eines Benutzernamens und eines Kennworts mit einem Web-Browser. Die Kennzeichnung des Eintrags wäre der Benutzername und die zu verschlüsselnden Daten enthielten das Kennwort. Das freiformatige Datenfeld könnte beliebige zusätzliche Daten über den Benutzer beinhalten. Den Kern unseres Tools bildet ein Serviceprogramm von Carsten Flensburg, das alle gebräuchlichen Aktionen mit Prüflisten ausführen kann. Für dieses Serviceprogramm haben wir eine Oberfläche erstellt, allerdings nicht mit DDS und RPG, sondern mit HTML, JavaScript, Cascading Style Sheets (CSS) und CGI-RPG. Für den Einsatz des Programms gelten folgende Voraussetzungen:

Die AS/400 muss als HTTP-Server mit der Berechtigung zum Ausführen von CGI-Programmen konfiguriert sein.
Sie müssen in der Lage sein, eine FTP-Verbindung zu Ihrem Web-Server herzustellen.
Die Prüfliste WEBPWD muss auf Ihrem System existieren. Zum Erstellen verwenden Sie folgenden Befehl:CRTVLDL VLDL(CGIDATA/WEBPWD) + TEXT(‘www passwords’)

Die Benutzeroberfläche ermöglicht folgende Aktionen mit Prüflisten von einem Web-Browser aus:

Eintrag hinzufügen
Eintrag ändern
Eintrag löschen
Eintrag prüfen
Eintrag abrufen (Diese Option werden Sie vielleicht entfernen wollen. Der Systemwert QRETSVRSEC legt fest, ob es möglich ist, entschlüsselbare Authentifizierungsdaten von Benutzerprofilen und Prüflisten auf dem System zu speichern. Dieser Systemwert betrifft nicht die Kennwörter von AS/400-Benutzerprofilen.)
Einträge auflisten (Diese Aktion listet wahlweise alle Kennwörter in einer Prüfliste auf.)

Wenn Sie das Dokument index.htm in Ihrem Browser aufrufen, können Sie unter den genannten Optionen auswählen. In Abbildung 1 ist die Option Add ausgewählt. Nachdem die erforderlichen Daten eingegeben wurden und auf Submit geklickt wurde, prüft eine JavaScript-Funktion namens CheckInput die Eingabe. Anschließend überträgt der Browser die HTML-Daten an den HTTP-Server. Falls bei der Eingabeprüfung ein Fehler festgestellt wird, erscheint eine entsprechende Meldung. Wenn die Eingabe fehlerfrei ist, wird mit dem Tag <FORM> das CGI-RPG-Programm PA9001 aufgerufen. PA9001 liest die Eingabe aus dem HTML-Formular, konvertiert sie in die Datenstruktur PA9001DS, ruft die entsprechende Prüflisten-Prozedur im Serviceprogramm CBX003 auf, und generiert (mit Hilfe der HTML-Schablone auf der AS/400) eine Antwort und zeigt sie im Browser an.

Die HTML-Dateien

Wenn Sie noch nicht über HTML-Kenntnisse verfügen, brauchen Sie keine Angst zu haben. HTML ist leicht zu erlernen und es gibt viele Online-Ressourcen für Einsteiger und Fortgeschrittene. Ein guter Einstieg ist z.B. www.idocs.com oder das (natürlich in HTML geschriebene) Online-Tutorial SelfHTML, das auch in deutscher Sprache unter zahlreichen Adressen zu finden ist (z.B. www.netzwelt.com/selfhtml/). Unser Programm ist mit Frames aufgebaut. Im linken Teil können die einzelnen Optionen angesteuert werden, und im rechten Teil werden die eingegebenen Daten angezeigt. Der HTML-Code ist einfach. Achten Sie auf folgende Anweisungen im Header:

Die beiden enthaltenen Anweisungen beziehen sich auf zwei externe Dateien: main.css und check-input.js. RPG-Programmierer können sich diese Anweisungen als /COPY-Dateien vorstellen, die allgemeine Daten oder Routinen enthalten, welche von mehr als einem Programm genutzt werden können. Main.css ist eine Textdatei, die den CSS-Code zum Formatieren der HTML-Dokumente enthält. Die Verwendung einer zentralen CSS-Datei erleichtert nachträgliche Änderungen an der HTML-Formatierung. Check-Input.cs ist eine Textdatei, die zwei JavaScript-Funktionen (vergleichbar mit RPG-Prozeduren) enthält. Die erste Funktion, CheckInput, prüft die Eingaben aus den Formularen und wertet sie aus. CheckInput verwendet einen Parameter, der steuert, welcher Teil des JavaScrupt-Codes ausgeführt werden soll. Die zweite JavaScript-Funktion, SetCursor, wird jedesmal aufgerufen, wenn ein Dokument geladen wird. Das geschieht im <BODY>-Abschnitt mit dem Ereignis onload. Weitere Informationen zu JavaScript finden Sie in zahlreichen Online-Dokumenten, die Sie am besten mit einem Suchdienst wie www.google.de und Suchbegriffen wie „JavaScript Anfänger“. Eine weitere interessante Stelle sind folgende Anweisungen:

Die erste Anweisung bezieht sich auf ein verborgenes Feld namens action. Dieses Feld steuert, wie sich das CGI-RPG-Programm verhält. Ein verborgenes Feld in HTML funktioniert genauso wie ein DDS-Feld mit dem Attribut non-display (ND). Verborgene Felder eignen sich gut dazu, vordefinierte Daten an ein CGI-Programm zu übergeben. Denken Sie aber daran, dass ein verborgenes Feld zwar nicht vom Browser angezeigt wird, dass es aber für jeden sichtbar wird, der sich den Quelltext vom Browser anzeigen läßt. Verwenden Sie also verborgene Felder nicht zum Speichern sicherheitskritischer Daten. Das zweite Feld ist ebenfalls ein verborgenes Feld, trägt den Namen dummy und hat auch den Inhalt „dummy“. Wenn der Benutzer die Eingabetaste drückt anstatt auf Submit zu klicken, wird das letzte Feld des Eingabeformulars nicht an das CGI-Programm übergeben. Das Dummy-Feld stellt deshalb sicher, dass das letzte eigentliche Datenfeld auch tatsächlich an das Programm übergeben wird. (Das Programm wurde unter OS/400, V4R4 geschrieben und getestet. Vielleicht tritt dieser Fehler in neueren Versionen nicht mehr auf. Sie können das selbst testen und gegebenenfalls das Dummy-Feld entfernen.

Aufruf des CGI-RPG-Programms

Das CGI-RPG-Programm wird mit einem <FORM>-Tag aufgerufen:

Die anderen Eingabefelder werden hier definiert:

Der <INPUT>-Tag definiert einen Button vom Typ Submit, und weil dieser zwischen den <FORM>-Tags definiert wird, ruft der Browser das im Parameter ACTION angegebene CGI-Programm auf. Dieses CGI-Programm könnte in jeder Sprache geschrieben werden, die Standard Readln CGI unterstützt; in unserem Fall ist es in RPG IV geschrieben. Beachten Sie auch, dass das Schlüsselwort ACTION die URL Ihres Web-Servers definiert. Wir haben den Server my_http_server genannt. Sie müssen diesen Namen in allen HTML-Dokumenten durch den Domain-Namen Ihres Systems ersetzen. Wenn Ihre iSeries keine Internet-Verbindung und keinen Domain-Namen hat, verwenden Sie einfach die IP-Adresse.

Das CGI-RPG-Programm in Aktion

Da RPG IV das direkte Lesen eines HTML-Formulars nicht unterstützt, müssen wir mit APIs arbeiten. Mit V4R4 hat IBM sieben CGI-APIs eingeführt, die im Serviceprogramm QZHBCGI in der Bibliothek QHTTPSVR zu finden sind. Wir fügen das Programm zu einem Bindeverzeichnis in der Bibliothek CGILIB hinzu ind beziehen uns mit dem Schlüsselwort BNDDIR in den H-Zeilen des CGI-RPG-Programms darauf. Das CGI-RPG-Programm verwendet für seine Aufgaben nur drei der CGI-APIs:

QtmhRdStin liest die Eingaben aus einem HTML-Formular
QtmhCvtDb konvertiert einen HTML-Datenstrom in eine AS/400-Datenbank oder -Datenstruktur
QtmhWrStout schreibt Daten zurück an den Browser

Bitte beachten: Da die CGI APIs in C geschrieben sind, muss auf die korrekte Groß-/Klein-Schreibung geachtet werden, da die Funktionen andernfalls nicht gefunden werden. Die erste Aktion des CGI-Programms ist das Lesen der Eingabedaten aus dem Formular. Dies geschieht in der Subroutine ReadStdIn unter Verwendung der API QtmhRdStin. Nachdem die HTML-Daten in das Programm eingelesen wurden, sieht die Variable RcvDta aus wie die Abbildung 2 dargestellten Daten.

Jetzt könnte man daran gehen, mit all den schönen neuen Funktionen von RPG IV die Zeichenkette zu zerlegen, aber es gibt einen einfacheren Weg. In der Subroutine CvttoDB wird das API QtmhCvtDb aufgerufen. Die Subroutine verteilt alle Felder aus dem HTML-Formular in eine AS/400-Datenbank oder -Datenstruktur. Wir haben eine externe Datenstruktur definiert, die dieselben Feldnamen enthält, die auch im HTML-Formular verwendet werden. Nach dem CALLB von QtmhCvtDb werden die Felder auf die Datenstrukturfelder abgebildet und landen somit in der Datenstruktur HTMLdata, die mit dem Schlüsselwort ExtName definiert wurde. Diese Art der Definition erleichtert spätere Programmänderungen. Nach dem Aufruf der Subroutine CvttoDB wird die Variable WrtDta, die die Daten enthält, die an den Browser zurückgegeben werden, mit dem konstanten Wert „Contenttype: text/html“ gefüllt. Diese Aktion ist wichtig, weil sie dem Browser mitteilt, dass HTML-Daten folgen. Andernfalls zeigt der Browser das Ergebnis nicht an. Beachten Sie auch, dass die HTML-Daten als ein einziger, langer Datenstrom an den Browser übergeben werden. Soll später einmal mehr im Browser angezeigt werden, so können zusätzliche Daten einfach an den bestehenden Inhalt von WrtDta angehängt werden. Der einzige Grund für die Verwendung der Konstante NewLine (Hex 15) ist, dass der generierte Code dadurch besser aussieht und leichter zu lesen ist.

Als Nächstes wird die Subroutine SubrAction aufgerufen, die den Aufruf des Serviceprogramms CBX003 entsprechend dem Inhalt der Variable Action und der Eingabewerte auf dem HTML-Formular vorbereitet und ausführt. Wird der Aufruf fehlerhaft beendet, so wird das Feld OOPS auf *ON gesetzt, umanzuzeigen, dass ein Fehler aufgetreten ist. Nach dem Aufruf von SubrAction folgt eine weitere Subroutine namens SetReply. Diese Subroutine füllt ein Feld namens HTMLreply entsprechend dem Inhalt des Fehlerflags OOPS und der im HTML-Formular ausgewählten Aktion. Nachdem die Antwort an den Browser vorbereitet ist, können wir darangehen, den HTML-Code aufzubauen, der vom Browser angezeigt werden soll. Wir verwenden eine HTML-Schablone, weil sie einfach zu ändern ist, und weil das CGI-RPG-Programm nur noch die fehlenden Daten einfügen muss. Diese Arbeit erledigt die Subroutine LoadHTML. Um die Schablone im Programm lesen zu können, wird die Eingabedatei mit der Quellenteildatei PA9001 in der Quellendatei CGILB/HTMLSRC überschrieben. (Beachten Sie, dass das Satzformat der HTML-Quellendatei von HTMLSRC in SRCREC umbenannt wurde, da das Programm sonst nicht umgewandelt werden könnte.) Die Teildatei enthält recht einfachen HTML-Code. Wir haben selbstdefinierte Schlüsselwörter verwendet, um mit den RPG-Funktionen %SCAN und %REPLACE die Rückgabedaten einfügen zu können.

Abbildung 3 zeigt ein Beispiel. Oben sehen Sie die HTML-Schablone und unten den Code zum Ersetzen des selbstdefinierten Schlüsselworts &reply. Ein Vorteil dieser Methode ist, dass das Programm auch dann noch funktioniert, wenn das Schlüsselwort an eine andere Stelle verschoben wird. In der Subroutine LoadHTML wird der gesamte HTML-Code in einem Feld namens WrtDta gesammelt, das 4500 Bytes lang ist. Wenn Ihr HTML-Code länger ist, müssen Sie die Größe der Variable anpassen. Jetzt müssen die Daten nur noch an den Browser übergeben werden. Die Subroutine WrtToHTTP verwendet dazu das API QtmhWrtStout. Mit der Anweisung CHECKR stellen wir die tatsächliche Länge der generierten HTML-Daten fest und speichern den Wert im Feld WrtDtaLen, das beim Aufruf von QtmhWrtStout mit übergeben wird. Nach dem API-Aufruf wird das Feld WrtDta initialisiert, was zwar eigentlich nicht nötig wäre, da das Programm mit *INLR = *ON beendet wird, was aber für mehr Klarheit sorgt und hilft, Probleme zu vermeiden, wenn *INLR einmal durch RETURN ersetzt werden sollte. Sobald *INLR auf *ON gesetzt wurde, wird das Ergebnis im Browser angezeigt.

Ein neues Werkzeug für Prüflisten

Wir hoffen, dieses Programm hat Ihnen einige Anregungen gegeben, eine modernere und interessantere Schnittstelle für ein gängiges RPG-Problem zu schaffen. Die Lösung bedient sich mehr neuer Elemente als eine reine DDS/RPG-Lösung, aber wenn Sie erst einmal angefangen haben, mit HTML und CGI zu arbeiten, werden Sie auch Spaß daran haben. Und Ihre Anwender ebenso. Weitere Informationsquellen zu HTML und CGI finden Sie nachstehend.

Weitere Informationen zu HTML und CGI

Entwicklung einer CGI-Anwendung mit RPG
News/400, März 1997
Validation List APIs Overview http://as400bks.rochester.ibm.com/pubs/html/as400/v4r5/ic2924/index.htm?info/apis/sec6.htm
Retain Server Security (QRETSVRSEC) http://publib.boulder.ibm.com/cgi-bin/bookmgr/bookmgr.cmd/BOOKS/qb3alc04/3.1.11

Installation des HTML- und RPG-Sourcecodes

Speichern Sie PA9001 und CBX003 in Ihrer CGI-Bibliothek (z.B. CGILIB).
Erstellen Sie in Ihrer CGI-Bibliothek eine neue Quellendatei mit dem Namen HTMLSRC, und speichern Sie die HTML-Teildatei PA9000 darin.
Erstellen Sie mit dem Befehl CRTBNDDIR ein Bindeverzeichnis:
CRTBNDDIR BNDDIR(CGILIB/CGIBNDDIR) TEXT(‚CGI-Bindeverzeichnis‘)
Hinweis: Wenn Sie bereits ein Bindeverzeichnis für die CGI-APIs angelegt haben, können Sie einfach CBX003 hinzufügen. Passen Sie dann jedoch das Schlüsselwort BNDDIR in PA9001 entsprechend an.
Fügen Sie CBX003 mit dem Befehl ADDBNDDIRE zum Bindeverzeichnis hinzu:
ADDBNDDIRE BNDDIR(CGILIB/CGIBNDDIR) OBJ(CGILIB/CBX003)
Speichern Sie PA9001DS in Ihrer CGI-Datenbibliothek (z.B. CGIDATA).
Erstellen Sie die Prüfliste WEBPWD in Ihrer CGI-Datenbibliothek:
CRTVLDL VLDL(CGIDATA/WEBPWD) TEXT(‚WWW Kennwörter‘)
Hinweis: Die Prüfliste wird mit der allgemeinen Berechtigung *EXCLUDE erstellt. Ändern Sie diese in *CHANGE, damit CBX003 die Prüfliste ändern kann.
Fügen Sie den Namen Ihres AS/400 HTTP-Servers in folgende HTML-Dokumente ein: vld_add.htm, vld_change.htm, vld_delete.htm, vld_list.htm, vld_retrieve.htm und vld_verify.htm. Sie können einen beliebigen Texteditor dazu verwenden. Ersetzen Sie einfach die Zeichenfolge „my_http_server“ durch den Domain-Namen oder die IP-Adresse Ihrer AS/400.
Laden Sie alle HTML-Dokumente sowie die CSS- und JavaScript-Dateien auf Ihren Web-Server. Der Einfachheit halber haben wir die JavaScript- und CSS-Dateien im selben Verzeichnis gespeichert wie die HTML-Dateien. Normalerweise würden Sie diese Dateien in separate Verzeichnisse stellen und die Verweise in den Header-Sektionen der HTML-Dateien entsprechend anpassen.
Rufen Sie mit Ihrem Browser die Adresse http://my_http_server/index.htm auf.