CGI verwenden

Version 2004 (Geändert)

Der 4D Web Server unterstützt CGIs (Common Gateway Interface). CGI sind für Web Seiten dasselbe wie Plug-Ins für 4D Methoden. Das CGI wird vom Web Server aufgerufen, führt eine Aufgabe aus und gibt die Antwort zurück: — eine komplette Web Seite oder HTML Code, der aus einer vom Server gesendeten Seite eingefügt wurde. CGI werden häufig eingesetzt, um Zugriffszähler anzuzeigen, Gästebücher (guestbook) zu verwalten, den Inhalt eines HTML Formulars als E-Mail zu versenden (form to mail), etc. Es gibt eine Vielzahl frei verfügbarer CGI, die meisten davon als „freeware".

Hinweis: CGI bezeichnet ursprünglich die Norm für die Kommunikation externer Anwendungen mit den HTTP Servern. Heute werden mit CGI auch die externen Anwendungen selbst bezeichnet.

Der 4D Web Server unterstützt CGIs auf zwei Arten:

• 4D Web Server kann CGIs im automatischen und manuellen Modus verwenden

• 4D Web Server kann eine Schnittstelle zu anderen HTTP Servern haben, die CGI Externals verwenden (nur Windows)

4D unterstützt alle Arten von CGI unter Windows und auf MacOS X. Ein CGI erscheint als ausführbares Programm, als Skript vom Typ PERL oder als DLL mit Schnittstelle zu einem Web Server.

- Anwendungen (.EXE) welche die "Konsole" und die Umgebungsvariablen verwenden. Der Quellcode ist in der Regel cross-plattform (Windows und Unix).Die CGI Namen lauten nnnn.exe oder nph-nnn.exe.

Weitere Informationen dazu finden Sie im Internet unter http://hoohoo.ncsa.uiuc.edu/cgi/.

- DLL ISAPI, das sind z.B. Externals für IIS (Internet Information Server). Ihre Namen lauten: nnnn.dll oder nph-nnn.dll. Zur Optimierung bleiben DLL, die auf diese Weise aufgerufen werden, im Hauptspeicher erhalten, bis der Web Server gestoppt wird.

Weitere Informationen dazu finden Sie im Internet unter http://www.microsoft.com/iis/.

- PERL Skripte, welche die "Konsole" und die Umgebungsvariablen verwenden. Diese CGI benötigen für die Ausführung einen Interpreten. Sie haben jedoch den Vorteil, dass sie vollkommen crossplattform sind (Windows, Unix und MacOS). Ihre Namen lauten

nnnn.pl, nph-nnnn.pl, nnnn.cgi oder nph-nnnn.cgi.

Weitere Informationen dazu finden Sie im Internet unter http://www.perl.com/.

Ein automatischer CGI Aufruf erfolgt je nach auszuführender Aufgabe des CGI über eine URL, eine Aktion oder einen in eine Seite eingefügten HTML Tag. Die HTML Folge muss in jedem Fall /cgi-bin/, gefolgt vom Namen des CGI und eventuell einem Zugriffspfad enthalten (mit der HTML Syntax) sowie eine Abfragefolge.

So löst z.B. die URL "http://195.1.2.3/cgi-bin/search.exe" die Ausführung des CGI search.exe aus. Setzen Sie <IMG SRC="/special/cgi-bin/counter.exe"> in einer HTML Seite, wird beim Senden der Seite das CGI counter.exe ausgeführt.

CGI werden nur aufgerufen, wenn sie im Ordner cgi-bin auf der obersten Ebene liegen. Dieser Ordner muss wiederum im Ordner des Web Servers oder in einem Unterordner davon liegen. Es kann pro Server mehrere Ordner cgi-bin geben. Dieser Ordner kann auch andere Dateien enthalten, jedoch werden von einem Web Client aus nur die ausführbaren Dateien aufgerufen.

Anordnung des CGI "Count.exe":

Beispiele für Anordnung und aufrufbare URL:

Ordner [MeineDB]

MeineDB.4db (Struktur) (http://195.1.2.3/)

Ordner [cgi-bin]

counter.exe (http://195.1.2.3/cgi-bin/counter.exe)

Ordner [Diverses]

	Ordner [cgi-bin]
	script.pl	(http://195.1.2.3/Diverses/cgi-bin/script.pl)

Um CGI im manuellen Modus aufzurufen, benötigen Sie den Befehl SET CGI EXECUTABLE. Damit können Sie ein CGI ausführen, ohne dass es für den Web Benutzer in der URL sichtbar wird. Weitere Informationen dazu finden Sie in der Beschreibung zu diesem Befehl.

Der Aufruf eines CGI verändert nie die 4D Umgebung (Auswahlmengen, Variablen...)

4D schreibt für die Antwort keine bestimmte Größe vor. Dagegen ist die Verarbeitung eines CGI auf 30 Sekunden begrenzt. Danach gibt der Web Server einen Fehler zurück.

Ein CGI wird immer außerhalb des Kontextes ausgeführt, egal, von welchem Modus aus er aufgerufen wurde.

Im kontextuellen Modus sollte jedoch kein CGI verwendet werden, das HTML Code zurücksendet, denn das kann den Kontext desynchronisieren.

Generiert der Aufruf eines CGI einen Fehler, gibt 4D eine der folgenden Antworten in Form einer HTML Standardseite zurück:

• Nicht gefunden: 4D hat das CGI nicht gefunden oder der PERL Interpreter ist nicht installiert

• Untersagt: Die angeforderte Anwendung liegt nicht im Ordner [cgi-bin]

• Timeout: Das CGI konnte die Anfrage nicht in 30 Sekunden bearbeiten

• Fehlerhafte Antwort: 4D konnte die Antwort des CGI nicht bearbeiten oder das DLL ISAPI hat eine Ausnahme ausgelöst

• Interner Fehler: Speicher voll, etc.

Hinweis: Funktioniert ein CGI nicht, prüfen Sie, ob die Ausführungsberechtigung des CGI passt und ob der Zeilenvorschub im CGI Skript korrekt ist.

Dieser Abschnitt richtet sich an Programmierer, die CGI für ihre 4D Datenbanken entwickeln wollen.

• Umgebungsvariablen

4D definiert die Umgebungsvariablen in Übereinstimmung mit den Spezifikationen CGI/1.1. Dabei gilt folgendes:

GATEWAY_INTERFACE: immer "CGI/1.1"

SERVER_SOFTWARE: immer "4D WebStar_D/Version"

SERVER_PROTOCOL: immer "HTTP/1.0"

SERVER_PORT_SECURE: enthält "1" bei abgesicherter HTTP Verbindung, sonst "0".

PATH_TRANSLATED: enthält den kompletten Zugriffspfad des HTML Ursprungs des Servers. Hinzugefügt wird der Pfadteil, der auf den Namen des CGI folgt. Aus Sicherheitsgründen kann dieser Teil nur die Abfolgen // oder .. enthalten.

Beispiel: Ursprung des Servers "C:/web". Für den Aufruf eines CGI vom Typ/cgi-bin/cgi.exe/path entspricht PATH_TRANSLATED "C:/web/path". Für den Aufruf eines CGI vom Typ /cgi-bin/cgi.exe/../path, sendet 4D den Fehler Untersagt zurück.

REMOTE_IDENT: Benutzername, sonst nicht definiert

HTTP_AUTHORIZATION, HTTP_CONTENT_LENGTH und HTTP_CONTENT_TYPE: nicht definiert.

ALL_HTTP und URL sind definiert, wenn ISAPI DLLs aufgerufen wird.

CERT_xxx und HTTPS_xxx sind definiert, wenn die Verbindung abgesichert ist (nur für DLL).

4D fügt zusätzlich zu den Standard Umgebungsvariablen Textvariablen vom Typ FORMVAR_Variablename hinzu:

- Wird die Anfrage mit der Methode "POST" gesendet, entsprechen diese Variablen den Eingabebereichen des Formulars (zum Beispiel FORMVAR_NAME, FORMVAR_VORNAME...) mit Ausnahme der binären Felder (INPUT TYPE="FILE"). Dieses System lässt sich mit den codierten Formularen "www/url-encoded" und "multipart/form-data" verwenden.

- Wird die Anfrage mit der Methode "GET" gesendet, entsprechen diese Variablen den Werten, die von der Frageabfolge übergeben werden.

Beispiel: Für die URL .../cgi.exe?name=smith&code=75 hat FORMVAR_NAME dann den Wert "martin" und FORMVAR_CODE den Wert "75").

Diese Funktionsweise vereinfacht die Bearbeitung von Formularen, da die Abfolgen a=1&b=2&... nicht analysiert werden müssen. Das CGI ist dann allerdings an 4D gebunden.

• Die von CGI zurückgegebenen Antworten bearbeiten

Beginnt der Name des CGI (Windows Anwendung oder PERL Skript) mit nph- (No Parsing Header), gibt 4D die Antwort unbearbeitet an den Web Client zurück. In diesem Fall muss sich CGI um die HTTP Norm kümmern.

Bei DLL ISAPI analysiert 4D die Antwort nie, egal ob die Vorsilbe nph- vorhanden ist oder nicht.

Ist das nicht der Fall, sendet 4D den HTTP Kopfteil zurück:

- Wird "Content-Type" nicht vom CGI angegeben, sendet 4D systematisch "Content-Type: text/html" zurück,

Ist "Location" angegeben, ignoriert 4D die anderen Elemente der Antwort und leitet HTTP um,

- Ist "Status" nicht angegeben, sendet 4D "HTTP/1.0 200 OK" zurück.

4D akzeptiert im Kopfteil der HTTP Antwort jede Art des Zeilenwechsels (Windows-CRLF, MacOS-CR, Unix-LF) und formt diesen entsprechend um.

Bei DLL ISAPI akzeptiert 4D die asynchrone Bearbeitung (HttpExtensionProc gibt HSE_STATUS_PENDING zurück). Der Aufruf von ServerSupportFunction (HSE_REQ_DONE_WITH_SESSION) muss innerhalb von 30 Sekunden stattfinden. Ist die Funktion TerminateExtension definiert, wird sie immer mit dem Wert HSE_TERM_MUST_UNLOAD aufgerufen.

Bei CGI WebSTAR erlaubt 4D das stückweise Senden von Antworten grösser als 32 Kb.

4th Dimension enthält die beiden Externals 4DISAPI.DLL und NPH-CGI4D.EXE. Damit kann ein HTTP Server Anfragen an den 4D Web Server übermitteln und 4D als CGI eingesetzt werden. Dieser Mechanismus lässt vorallem das Entwickeln von Systemen zu, in denen ein HTTP Server, der im gesicherten Modus läuft, einen nicht gesicherten 4D Web Server abfragen kann.

Hinweis: Diese beiden Externals sind nur unter Windows verfügbar.

• Das External 4DISAPI berücksichtigt die Festlegungen von ISAPI (Internet Services Application Programming Interface). Diese Technologie ISAPI wurde ursprünglich von Microsoft® für den IIS Server entwickelt, ist aber inzwischen zu zahlreichen HTTP Servern kompatibel, wie z.B. Netscape®, Apache® oder Sambar®

• Das External NPH-CGI4D.EXE berücksichtigt die Festlegungen von CGI (Common Gateway Interface) und ist für alle CGI kompatiblen Server verwendbar.

Beide Externals funktionieren auf dieselbe Art und Weise. Unter HTTP Servern ist die Kompatibilität zu CGI weiter verbreitet. Die Leistungsstärke der CGI-Externals ist im allgemeinen geringer als die der ISAPI-Externals.

Diese Externals funktionieren folgendermaßen:

Ein HTTP Server "A" publiziert Seiten im Internet, ein anderer HTTP Server "B" fungiert als 4D Server im Intranet. Damit diese beiden Server miteinander kommunizieren können, genügt es, in das Verzeichnis [Scripts] von Server A ein 4DISAPI- oder NPH-4DCGIl-External zu legen.

Sendet ein Web Browser eine Anfrage an Server A, überträgt er diese über das External 4D ISAPI bzw. NPH-4DCGI mit Hilfe der URL an Server B. Die Antwort wird dann in umgekehrter Weise über den Navigator geleitet. Das External verändert nie die Anfrage bzw. die HTTP Antwort selbst.

Im allgemeinen überträgt das External an Server B den Teil der URL, die auf dessen eigenen Aufruf folgt, einschliesslich der Frageelemente.

Beginnt der Name des CGI mit NPH- (No Parsing Header), muss der Server nicht den HTTP-Kopfteil der Antwort analysieren. Dann kümmert sich das CGI selbst um die Formatierung.

Die an Server A gesendete Anfrage kann in Klartext oder im gesicherten Modus (SSL) erfolgen. Die beiden HTTP Server und das External 4DISAPI.DLL kommunizieren in Klartext miteinander.

Hinweis: Die Externals 4DISAPI und NPH-4DCGI funktionieren nur im nicht kontextuellen Modus des 4D Web Servers.

Beispiel zur Funktionsweise des Externals 4DISAPI.DLL

• Die Externals erkennen die Methoden GET, HEAD und POST, sie verwalten die verschiedenen Stadien, die 4D zurücksendet (200 OK, 302 Moved Temporarily, 404 Not Found...).

• Die Authentifizierung auf HTTP Ebene lässt sich dagegen nicht über das External 4DISAPI oder NPH-CGI4D durchführen. Dafür ist ein HTML Formular notwendig, welches sich bei einer gesicherten Verbindung mühelos einplanen lässt.

Hinweis: Externals dienen hauptsächlich zum Empfangen und Zurücksenden von dynamischen Daten, insbesondere zum Datenversand. Der einfache Dienst von Web Seiten bietet bei der Übertragung mit den Externals ISAPI oder CGI keine optimale Leistung

Zur Installation der Externals genügt es, die Dateien 4DISAPI und NPH-CGI4D in das Verzeichnis [Scripts] des HTTP Servers zu kopieren.

Jedes installierte External enthält eine Datei mit der Endung *.INI mit der Konfiguration. Sie muss genauso heissen wie das External, z.B. 4DISAPI.INI und im gleichen Ordner liegen.

Sie können einen HTTP Server einrichten, der auf mehrere andere HTTP Server zielen kann. Platzieren Sie dazu im Verzeichnis [Scripts] des HTTP Servers ebensoviele Externals wie Zielserver, die Sie entsprechend umbenennen, z.B. 4DISAPI2.DLL, 4DISAPI3.DLL, etc. Vergessen Sie nicht, pro External auch eine Konfigurationsdatei einzurichten und entsprechend zu benennen, z.B. 4DISAPI2.INI, 4DISAPI3.INI, etc.

Die Datei mit der Endung .INI besteht nur aus dem Abschnitt:

[Forward]. Dieser akzeptiert folgende Befehle:

• TargetServer =

Name oder IP Adresse des Web Ziel Servers, z.B. Meinserver.net oder 192.193.194.195). Sie können die Zeile leer lassen, um einen Server über seine Adresse festzulegen, wenn der Name nicht verfügbar ist.

Der Name "localhost" wird als die Adresse 127.0.0.1. erkannt

Diese Adresse wird standardmässig verwendet.

• TargetPort =

Port, auf den der Zielserver reagiert, z.B. 81. Standardmässig wird der Port 8080 verwendet.

• Timeout =

Maximale Wartezeit in Sekunden für die Antwort des Servers. Standardmässig ist 30 Sekunden vorgegeben.

• Allowed =

Liste der zugelassenen URL, getrennt durch Komma; zum Beispiel: /pages,/img, um nur URL zuzulassen, die beginnen mit /pages und /img. Wollen Sie die gesamte Web Site zulassen, tragen Sie nur einen Schrägstrich ein (Standardeinstellung).

• Forbidden =

Liste der untersagten URL, getrennt durch Komma; zum Beispiel: /4dmethod,/pages2, um URL zu sperren, die mit /4dmethod und /pages2 beginnen. Wollen Sie nichts sperren, lassen Sie die Liste leer. Das ist auch die Standardeinstellung.

Gemäss der oben genannten Beispiele für zugelassen und gesperrt, gilt für die URL des Zielservers:

Wird eine nicht zugelassene URL angefordert, gibt das External direkt den Fehler "403 Forbidden" zurück.

4DISAPI und NPH-CGI4D unterstützen folgende URLs:

4D Aufruf (4D erhält nur den URL Teil, der nach dem External-Namen liegt):

http://server-address/cgi-bin/4disapi.dll/[Path]

http://server-address/cgi-bin/nph-cgi4d.exe/[Path]

External überprüfen (Echo auf die Anfrage):

http://server-address/cgi-bin/4disapi.dll/~~echo

http://server-address/cgi-bin/nph-cgi4d.exe/~~echo

Information über das External (technischer Support):

http://server-address/cgi-bin/4disapi.dll/~~info

http://server-address/cgi-bin/nph-cgi4d.exe/~~info

Folgende Information wird zurückgegeben:

• Name und Version des External, z.B. "Script name: 4disapi.dll (6.7.0b1.2)"

• Name und Version des aufrufenden Servers, z.B. "Server software: 4D_WebStar_D/6.7"

• Version des HTTP Protokolls, z.B. "Server protocol: HTTP/1.0"

• Version des CGI Protokolls, z.B. "Gateway interface: CGI/1.1"

Zielserver prüfen (ist der Server verfügbar?):

http://server-address/cgi-bin/4disapi.dll/~~target

http://server-address/cgi-bin/nph-cgi4d.exe/~~target

Die Antwort lautet:

• "Good: target server reached.": Zielserver hat geantwortet (unabhängig vom Inhalt der Antwort).

• oder "Bad: target server not reached.": Zielserver wurde nicht gefunden oder hat nicht geantwortet.

In diesem Fall gibt es folgende Fehlerursachen:

- Konfigurationsdatei fehlt;

- Zieladresse oder Port ist falsch;

- Zielserver ist ausgeschaltet;

- Zielserver hat die Anfrage erhalten, kann aber nicht antworten.

Hinweis zu 4D WebSTAR: 4D WebSTAR® gehört auf Mac OS zu den gängigsten Web Servern. Zwischen 4th Dimension und 4D WebSTAR wurden verschiedene Möglichkeiten für Interaktionen entwickelt, insbesondere das 4D WebSTAR Plug-In 4D Link. Weitere Informationen dazu finden Sie in der Dokumentation zu 4D WebSTAR.

SET CGI EXECUTABLE, SET ENVIRONMENT VARIABLE.