Am Beispiel der Implementierung eines Web-Gästebuchs werden die Grundlagen der Programmierung mit dem Common Gateway Interface gezeigt. von Edward R. Smith Mit der Verfügbarkeit des Common Gateway Interface (CGI) im Internet Connection/400 HTTP Server wird die AS/400 zur Plattform für die Entwicklung interaktiver Web-Anwendungen. CGI ist ein Standardprotokoll für Web-Server, das die direkte Interaktion zwischen Server-Programmen (z.B. RPG- oder CL-Programmen) und einem Web-Browser ermöglicht.
Die Load ’n‘ go Datei zu diesem Artikel finden Sie hier.
Mit dem CGI der AS/400 können CGI-Anwendungsprogramme (sogenannte Scripts) in RPG statt in anderen Sprachen wie C oder Perl geschrieben werden. Mit etwas Übung kann man vorhandene RPG-Kenntnisse zum Erstellen von CGI-Anwendungen wie der hier vorgestellten einsetzen. Die RPG-CGI-Programmierung bietet zahlreiche Möglichkeiten, Kunden oder Anwender über das Web zu erreichen, aber allgemein werden in der CGI-Programmierung vier Funktionen am häufigsten genutzt: – das Aufnehmen von Formulardaten – das Abrufen von CGI-Umgebungsvariablen (z.B. einer Suchzeichenfolge oder einer Browser-IP-Adresse) – das Umleiten eines Browsers zu einer anderen Web-Seite – das Generieren von HTML-Inhalten zur direkten Anzeige in einem Browser Eine einfache Anwendung demonstriert die erste und die dritte dieser Funktionen (Formulardaten-Aufnahme und Browser-Navigation). Diese Anwendung ist ein Gästebuch, das Namen, Adressen und Kommentare der Besucher einer Web-Site aufzeichnet. Anhand dieses CGI-Beispielprogramms wird gezeigt, wie man Daten aus einem Web-Eingabeformular liest und in eine AS/400-Datenbankdatei überträgt, und wie man einen Browser zu einer anderen Web-Seite weiterleitet. Die im Beispielprogramm angewendeten Verfahren basieren auf den HTTP-Funktionen von IBMs HTTP-Server und können für fast alle Anwendungen eingesetzt werden, die Benutzerdaten in Datenbankdateien speichern.
Die Gästebuch-Anwendung wird gestartet, wenn ein Web-Anwender auf das Hypertext-Link klickt, das das Formular für den Eintrag im Gästebuch aufruft (Abbildung 1). Nachdem er Name und Anschrift in die Felder des Formulars eingetragen hat, klickt der Benutzer auf den Button zum Absenden der Eingaben, der mit diesen Daten ein CL-Programm aufruft, das im HTML-Code des Formulars angegeben wurde. Die Daten werden über die Methode »standard input« an das Programm übergeben. (Standard input und standard output sind Methoden, die ein CGI-Anwendungsprogramm verwendet, um Daten über die Tastatur zu empfangen und auf dem Bildschirm auszugeben.) Ein RPG-CGI-Programm übernimmt die Daten, paßt sie an die AS/400-Datenbankfelder an, schreibt einen Satz in die Datenbankdatei und leitet den Browser an die »Danke«-Seite weiter. Um keine leeren Sätze in die Datei zu schreiben, prüft das RPG-Programm, ob das Namensfeld und andere obligatorische Felder ausgefüllt wurden. Sind die Felder leer, so wird der Browser zur Fehlerseite weitergeleitet, die erläutert, welche Angaben fehlen.
Zunächst ist zu klären, wo die Objekte (die HTML-Datei und die CGI-Programme) gespeichert werden, und wie der Zugriff darauf ermöglicht werden soll. Die HTML-Dateien der Gästebuch-Anwendung sind im IFS-Verzeichnis GBK gespeichert und die CL-und RPG-Programme in der Bibliothek CGIBIN. Bevor ein AS/400-RPG-Programm mit HTML gestartet werden kann, muß dieses Programm über HTTP-Server-Direktiven freigegeben werden, die mit dem Befehl
WRKHTTPCFG (Mit HTTP-Konfiguration arbeiten) erfaßt werden. Diese Direktiven sind die Bewacher der ausführbaren AS/400-Programme und als solche eine wichtige Sicherheitskomponente des Web-Servers. (Weitere Informationen über Direktiven finden Sie in »Sicherheit für die InternetConnection/400« in Heft 1/97, Seite 36.) Die HTTP-Konfigurations-Direktiven mit denen einem Browser der Zugriff auf die Gästebuch-Anwendung ermöglicht wird, lauten: MAP /GBK/* /gbk/* MAP /CGIBIN/* /cgibin/* ENABLE POST PASS /gbk/* EXEC /cgibin/* /QSYS.LIB/CGIBIN.LIB/* Die beiden ersten MAP-Direktiven werden wegen der unterschiedlichen Handhabung der Groß-/Kleinschreibung in OS/400 und HTML benötigt. Die AS/400-Dateisysteme mit Ausnahme von QOpenSys unterscheiden zwar nicht zwischen Groß- und Kleinschreibung, aber HTML und damit auch HTTP-Konfigurationsdirektiven. MAP-Direktiven lösen dieses Problem, indem sie Kleinbuchstaben in Großbuchstaben umsetzen.
Die beiden MAP-Direktiven stellen sicher, daß die nachfolgenden, kleingeschriebenen Angaben in den PASS- und EXEC-Direktiven richtig funktionieren. Der Stern ist ein Platzhalter mit der Bedeutung »jede beliebige Zeichenfolge an dieser Position«. In der ersten MAP-Direktive bedeutet der Stern z.B. »übersetze alles, das mit /GBK/ beginnt, so daß es mit /gbk/ beginnt«. Die ENABLE-Direktive erlaubt es, die Methode POST für Client-Anforderungen aus jedem HTML-Formular zu verwenden, das der Server bereitstellt. Die Methode POST wird zur Verarbeitung von Eingabe-Formularen verwendet. Die Direktiven PASS und EXEC sind die Wachposten, die kontrollieren, auf welche Dateien und Programme vom Web aus zugegriffen werden kann. Die dargestellte PASS-Direktive erlaubt den Zugriff auf alle Datenbankdateien im Verzeichnis GBK, und die EXEC-Direktive ermöglicht die Ausführung aller Programme in der Bibliothek CGIBIN.
Wer verhindern will, daß Gästebuch-Anwender auf AS/400-Daten zugreifen, verwendet Überschreibungen und qualifizierte Objektnamen in einem CL-Frontend-Programm, um Dateien und andere Objekte in Bibliotheken zu speichern, auf die ein Web-Browser nicht direkt zugreifen kann. (Das kurz vorgestellte Programm GBKCL arbeitet so, weil die Bibliothek CGIBIN nicht in der Bibliotheksliste des Servers steht.) Wie immer unter OS/400, haben Objekt- und Benutzerberechtigungen das letzte Wort in Sicherheitsfragen. HTTP-Anforderungen werden unter dem Benutzerprofil QTMHHTTP ausgeführt, und CGI-Programme laufen unter dem Benutzerprofil QTMHHTP1. Die standardmäßigen Berechtigungen für den allgemeinen Objektzugriff sollten in der Regel ausreichen. Wenn auf gemeinsame Ordner zugegriffen werden soll (das gebräuchliche Speichermedium für PC-Dateien – jetzt als Verzeichnis QDLS geführt), muß das Benutzerprofil QTMHHTTP zum Systemverzeichnis hinzugefügt werden.
Der Zugriff auf die Gästebuch-Seite mit einem Browser zeigt das Eingabeformular in Abbildung 1 an. Wie in der HTML-Quelle (Abbildung 2) gezeigt, wird eine HTML-Tabelle verwendet, um die Eingabefelder darzustellen. HTML-Tabellen eröffnen mehr Möglichkeiten bei der Anordnung von Text, Listen und Eingabefeldern als einfache HTML-Anweisungen. Die meisten Eingabefelder sind vom Typ TEXT. Für das Feld COMMENT wird ein TEXTAREA-Tag benutzt, weil es mehrzeilige Texteingaben erlaubt. Mit einem CHECKBOX-Typ kann der Anwender bestimmen, ob sein Name und seine Bemerkungen in einer anderen Web-Seite angezeigt werden dürfen. Der Anwender gibt seinen Namen und seine Anschrift in die dafür vorgesehenen Felder ein, und klickt dann auf den Button »Add to Guestbook«, um den Browser folgende FORM ACTION-Anweisung ausführen zu lassen:
form 400-server=““ ab.=““ action=“/cgibin/gbkcl.pgm“ als=““ anweisung=““ as=““ attribut=““ aufgerufen=““ berschreibung=““ bevor=““ browser=““ cgi-programms=““ cgi-verarbeitung=““ cl-frontend=““ das=““ daten=““ den=““ der=““ des=““ die=““ dieser=““ eigentliche=““ eine=““ einfaches=““ eingegebenen=““ es=““ fordert=““ form=““ formulardaten=““ gbk=““ gbkcl.pgm=““ hrt.=““ hrung=““ im=““ in=““ iv-programm=““ method=“post“ mit=““ post-format=““ rpg=““ rpg-cgi-programm=““ ruft=““ wenn=““ wird=““ wurde.=““ zu=““ zur=““>
Man kann das RPG-CGI-Programm GBK als Vorlage für eigene CGI-Skripts benutzen. (Die Schritte zum Erstellen des Programms GBK werden im Kasten »Erstellen des CGI-Programmobjekts GBK« beschrieben. GBK führt die folgenden drei Arbeitsschritte aus: 1. Abrufen der Formulareingaben von Standard Input mit dem API QtmhRdStin (Read Standard Input), einem der drei im Programm verwendeten CGI-APIs. 2. Umsetzen des ASCII-Datenstroms in EBCDIC und Abbilden der Werte auf Datenbankfelder mit dem API QtmhCvtDb (Convert to Database). 3. Bei unvollständigen Benutzereingaben Umleitung des Browsers zur Seite OOPS.HTM. Bei vollständiger Eingabe Schreiben eines Datensatzes in Datenbankdatei GUESTBOOK und Weiterleiten des Browsers zur Seite THANKS.HTM mit dem API QtmhWrStout (Write Standard Output). Jedes vom Programm GBK aufgerufene CGI-API erwartet eine Reihe von Parametern, von denen einige gemeinsam von mehreren APIs benutzt werden. Der Parameter RcvDta speichert z.B. von Standard Input eingehende Daten (wenn QtmhRdStin aufgerufen wird) und dient gleichzeitig als Datenquelle beim Parsen und Umwandeln in Datenbankfelder (beim Aufruf von QtmhCvtDb).
Im Mainline-Abschnitt des CGI-Programms GBK besteht die erste Aufgabe darin, die Eingaben das Benutzers zu lesen. Das dazu verwendete API QtmhRdStin erwartet vier Parameter: RcvDta Variable für die empfangenen Daten RcvDtaLn Variable für die Länge der Variable RcvDta RcvValLn Variable für die Länge des Inhalts von RcvDta QUSEC Fehler-Datenstruktur RcvDtaLen sollte groß genug sein, um die erwarteten Daten aufzunehmen und muß vor dem Aufruf von QtmhRdStin initialisiert werden. GBK richtet RcvDtaLn mit einer Länge von 1024 Stellen ein, was auf jeden Fall ausreichen sollte. RcvValLn und QUSEC enthalten Rückgabewerte des APIs QtmhRdStin. Der Parameter QUSEC wird von
vielen, von IBM gelieferten APIs in der gleichen Form verwendet. Seine Definition kann aus der Teildatei QUSEC in der Datei QSYSINC/QRPGLESRC kopiert werden. Die Datensstruktur QUSEC kann bei Bedarf verlängert werden, um mehr Platz für Fehlerinformationen aufzunehmen. QtmhRdStin liest die an Standard Input übergebenen Daten und speichert sie in der Variable RcvDta in einem Format, das nach folgendem Schema aufgebaut ist: var1=wert1&var2=wert2&var3=wert3 Die Daten liegen noch in »Escape«-Form vor, was bedeutet, daß bestimmte ASCII-Zeichen in eine ASCII-Escape-Sequenz umgesetzt sind, um problemlos im Internet transportiert werden zu können. Ein Leerzeichen wird z.B. zu einem Pluszeichen (+) umgewandelt, und andere Zeichen, wie Komma (,) oder Schrägstrich (/) erscheinen als %xx, wobei xx dem hexadezimalen ASCII-Code für das jeweilige Zeichen entspricht. Die Eingabe »Joe Green, CDP« würde z.B. so erscheinen: GBNAME=Joe+Green%2A+CDP
Die nächste Aufgabe des CGI-Programms ist die Umwandlung der Standard-Input-Daten in eine von der AS/400 verwendbare Form. Dafür ist das API QtmhCvtDB zuständig. Es übersetzt Escape-Strings zurück in ihre ursprünglichen Zeichen, wandelt ASCII in EBCDIC um und bildet die Feldwerte auf extern beschriebene Datenbankfelder ab. QtmhCvtDB kann Daten auch in numerische Felder übergeben. Das API QtmhCvtDB erwartet sieben Parameter: DBFile Name der Bibliothek und der Datenbankdatei (z.B. BIBLxxxxDATEIxxxx) RcvDta Variable mit den umzuwandelnden Daten RcvDtaLn Länge der zuvor angegebenen Variable GBKDS externe Datenstruktur mit den Felddefinitionen der Datenbankdatei DBFmtLn Länge des Satzformats der Datenbankdatei CvtResp Antwortcode QUSEC Fehler-Datenstruktur Hinweis: Im gegenwärtigen Zustand gibt das API QtmhCvtDB einige Zeichen (z.B. Rufzeichen, Komma und Schrägstrich) unübersetzt als ASCII-Hexcode zurück, was in nachfolgenden Anwendungen zu unvorhersehbaren Ereignissen führen kann. Hat ein Zeichen z.B. einen Hexcode kleiner als X’40‘ und wird auf einem 5250-Bildschirm angezeigt, so wird es als Bildschirmattribut interpretiert (z.B. Umkehranzeige). RPG-Code für die Behandlung dieses Problems ist von den IBM-AS/400-Partnern in der Development Computing Homepage unter Fehler! Verweisquelle konnte nicht gefunden werden. erhältlich. (Der Code ist in einer AS/400-Bibliothek mit CGI-Programmbeispielen enthalten.) Bezüglich dieses Problems ist es sicher auch sinnvoll, auf dem neuesten PTF-Stand zu sein. Nachdem das Programm GBK das API QtmhCvtDB aufgerufen hat, enthalten die in der extern beschriebenen Datenstruktur GBKSDS beschriebenen Felder die ausgelesenen Werte. Der Parameter CvtResp enthält einen Wert, der angibt, wie gut die Umwandlung durchgeführt werden konnte, was bei der Fehlersuche sehr hilfreich sein kann. Die zurückgegebenen Werte haben folgende Bedeutung: 0 jedes HTML-Eingabefeld wurde auf das
entsprechende Datenbankfeld abgebildet -1 mindestens ein Datenbankfeld wurde in der HTML-Quelle nicht angesprochen -2 mindestens ein HTML-Feld wurde in der Datenbankdatei nicht angegeben -3 die beiden zuvor genannten Fehlerbedingungen treffen zu -4 einige Daten könnten unbrauchbar sein Die übrigen Parameterwerte (mit Ausnahme von QUSEC) sind vor dem Aufruf des APIs individuell zu versorgen. Voraussetzung für die Verwendung von QtmhCvtDB ist, daß die im HTML-Formular verwendeten Namen der Eingabefelder mit den Namen in der Datenbankdatei und in der extern beschriebenen Datenstruktur übereinstimmen. Das Parameter DBFile gibt die Datenbankdatei als Aneinanderreihung der Bibliothek und des Dateinamens an, und der Parameter GBKDS verweist auf die extern beschriebene Datenstruktur mit den Feldbeschreibungen der Datenbankdatei. Diese Parameter sind auch dann erforderlich, wenn die Datenbankdatei bereits in den F-Spezifikationen beschrieben ist. Nachdem das API QtmhCvtDB die eingegebenen Daten in einen AS/400-Datensatz umgewandelt hat, kann das Programm GBK den Satz in die Datenbankdatei GUESTBOOK schreiben. Um zu verhindern, daß leere Sätze in die Datenbank geschrieben werden, prüft das Programm GBK, ob die Felder Name, Ort und Staat gefüllt sind. Die Datenbankdatei GUESTBOOK hat keinen Schlüssel, und GBK prüft nicht, ob ein Anwender bereits in der Datei gespeichert ist. Bevor der Datensatz geschrieben wird, werden mit einer TIME-Operation Datum und Uhrzeit festgehalten und im Feld GRABBED gespeichert.
Jedes CGI-Programm muß einige HTML-Statements an Standard Output schreiben, um den Anwender mitzuteilen, daß das Programm beendet ist und er nichts mehr eingeben muß. Diese HTML-Anweisungen können einfach den Browser zu einem existierenden HTML-Dokument weiterleiten oder selbst ein HTML-Dokument darstellen. Das API QtmhWrtStout erwartet drei Parameter: StdOutDta Variable mit den auszugebenden Daten StdOutLn Länge der Daten in StdOutDta QUSEC Fehler-Datenstruktur Ein CGI-Programm kann mehrfach auf Standard Output ausgeben, aber der HTTP-Server wartet, bis das Programm beendet wurde, bevor er die CGI-Ausgabe an den Browser absendet. Das Programm GBK leitet die Ausgabe an den Browser mit der HTTP-Anweisung »location« um: ‚Location: Fehler! Verweisquelle konnte nicht gefunden werden.‘ Zum Schließen des Antwort-Headers sendet GBK eine leere Zeile, um dem Browser mitzuteilen, daß die Datei abgeschlossen ist. Andernfalls würde der Browser weiter auf Daten warten und für den Anwender gesperrt bleiben. Eine leere Zeile wird über das API QtmhWrStout mit zwei X’15‘ Zeichen ausgegeben. (I/Nets WebServer/400 verwendet X’0D15′ für Leerzeilen.) Das Programm GBK arbeitet mit einer benannten Konstante (CRLF) mit dem Wert X’15‘. Wenn eines der vier Schlüssel-Eingabefelder leer ist, wird die Ausgabe im Programm GBK mit einer EVAL-Anweisung an die Seite OOPS.HTM umgeleitet; enthalten die Felder Werte, so leitet GBK die Ausgabe an die Seite THANKS.HTM weiter. In jedem Fall muß CRLF an das Ende von StdOutDta angehängt werden. Dies ist die erste von zwei CRLF-Sequenzen, die zur Ausgabe einer Leerzeile benötigt werden. Die Subroutine SrStdOut fügt ein zweites CRLF hinzu und zählt die zu sendenden Zeichen, bevor das API QtmhWrStout aufgerufen wird. Die Beispielanwendung läßt sich als Grundstock für die Entwicklung komplexerer CGI-Skripts in
RPG verwenden. Wer sich näher mit RPG und CGI befaßt, wird sicher viele neue Möglichkeiten zum Einsatz der AS/400 als Web-Server und Datensammlungs-Tool finden. Man kann ein funktionstüchtiges Beispiel der Gästebuch-Anwendung testen, wenn man mit dem Browser die URL Fehler! Verweisquelle konnte nicht gefunden werden. anwählt. (Hinweis: die Zahl 81 gibt die Port-Nummer des HTTP-Server-Systems an, auf dem die Anwendung läuft. Wer GBK mit diesem Server verwenden will, muß an den entsprechenden zwei Stellen im Hauptprogramm von GBK »:81« hinter »http://www.ibmuser.com…« angeben.) [Beginn Kasten »Erstellen des CGI-Programmobjekts GBK«]
![Künstler Burgy Zapp [http://burgyzapp.de]](http://newsolutions.de/it/wp-content/uploads//ip4_IMG_3697_Negativ.jpg)
