HTML::Embperl_ - Erstellen dynamischer Websites mit Perl Embperl ist ein Perlmodul welches es erlaubt beliebigen Perlcode in HTML Dokumente einzufügen. Wenn Sie mehr als eine einzelne Webseite erstellen, sollten Sie auch einen Blick auf "perldoc EmbperlObject" werfen, welches es erlaubt Websites aus wiederverwendbaren Objketen zusammenzusetzen. Zusätzlich erlaubt es "perldoc HTML::Embperl::Mail" die resultierenden Seiten per EMail zu verschicken.

mod_perl Konfiguration
Um HTML::Embperl als content handler unter mod_perl laufen zu lassen, sind folgende Zeilen in der Apache Konfigurationsdatei httpd.conf nötig: Beipiel für Apache httpd.conf: SetEnv EMBPERL_DEBUG 2285 <Location /embperl/x> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI </Location> Diese Konfiguration bewirkt, dass mod_perl Embperl für alle Dateien, die im Unterverzeichnis, das mittels der URI <l>/embperl/x</l> angesprochen wird, liegen, als content handler aufruft. Embperl kann dann die Datei entsprechend bearbeiten und das Ergebnis zum Browser schicken. Eine andere Möglichkeit ist, alle Dateien mit einer bestimmten Endung von Embperl bearbeiten zu lassen. Eine Konfiguration dafür würde wie folgt aussehen: SetEnv EMBPERL_DEBUG 2285 <Files *.epl> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI </files> AddType text/html .epl HINWEIS: Wenn mod_perl mit "USE_DSO" übersetzt ist, darf Embperl nicht beim Starten des Server geladen werden!

Andere Arten Embperl zu nutzen
Embperl kann ebenso von der Befehlszeile aus aufgerufen werden oder als normales CGI Skript ausgeführt werden. Weiterhin können andere Perlprogramme oder -module es direkt aufrufen. Der Aufruf von der Befehlszeile sieht folgendermaßen aus (erste Zeile Unix, zweite Zeile Windows): "embpexec.pl [-o outputfile] [-l logfile] [-d debugflags] htmlfile [query_string]" "embpexec.bat [-o outputfile] [-l logfile] [-d debugflags] htmlfile [query_string]" Datei welche von Embperl bearbeitet werden soll. Optional. Hat die selbe Bedeutung wie die Umgebungsvariable QUERY_STRING eines CGI Skripts. QUERY_STRING beinhaltet alles nach dem ersten "?" in der URL. query_string sollte URL kodiert sein. Default ist kein query_string. Optional. Gibt den Dateinamen an, in den das Ergebnis geschrieben wird. Default ist die Standardausgabe. Optional. Name der Logdatei. Default ist "/tmp/embperl.log". Optional. Gibt an, welche Debuginformationen in die Logdatei geschrieben werden. (siehe "EMBPERL_DEBUG" für mögliche Werte) Um Embperl als CGI Skript zu nutzen, müssen Sie die Datei "embpcgi.pl" (bzw. "embpcgi.bat" unter Windows) in Ihr CGI Verzeichnis kopieren (oft "/cgi-bin"). Zum Aufrufen verwenden Sie die URL http://www.domain.de/cgi-bin/embpcgi.pl/uri/ihres/embperl/dokuments Die extra Pfadinformationen die "embpcgi.pl" übergeben werden, geben dabei den Ort des Embperl Dokuments an. Unter Apache kann "embpcgi.pl" auch als Handler definiert werden: <Directory /pfad/zu/ihren/embperl/dokumenten> Action text/html /cgi-bin/embperl/embpcgi.pl </Directory> HINWEIS 1 Die Datei embpexec.pl darf aus Sicherheitsgründen nicht mehr als CGI Skript genutzt werden! HINWEIS 2: Um die Sicherheit von CGI Skripten sicher zustellen, empfiehlt es sich mittels EMBPERL_ALLOW den Zugriff zu beschränken.

Embperl aus Embperl Dokumenten oder anderen Perl Programmen/Modulen aufrufen
Die Funktion "Execute" kann genutzt werden, um Embperl aus anderen Perlmodulen oder -programmen aufzurufen. Ebenso ist es möglich andere Dokumente (z.B. Kopf- oder Fußzeilen) in Embperlseiten einzufügen. Die Kurzform müssen lediglich Dateinamen und ggf. Parameter für das aufzurufende Dokument als Argumente angegeben werden: Execute ($filename, @params) ; Die Langform erwartet eine Referenz auf einen Hash als Argument: Execute (\%params) ; Die Kurzform entspricht folgendem Aufruf in der Langform: Execute ({inputfile => $filename, param => \@params}) ; Parameter für die Langform sind: Mittels "inputfile" wird die Datei angegeben, die von Embperl bearbeitet werden soll. Ist der Parameter "input" ebenso vorhanden, sollte "inputfile" einen eindeutigen Namen spezifizieren. Jedesmal wenn Embperl den selben Namen sieht, geht es davon aus, daß die Quelle die selbe ist und verwendet den selben Packagenamen, sowie compiliert die Perlteile nur wenn "mtime" sich ändert oder undefiniert ist. Ruft die durch diesen Parameter angegebene Funktion auf (siehe auch [$ "sub" $]). Momentan muß die Funktion entweder in der selben Embperldatei definiert sein oder die Embperldatei muß vorher importiert worden sein. Referenz auf einen Skalar, welcher den Quellentext enthält. inputfile sollte ebenso angegeben werden, um die Quelle zu benennen. Der Name kann dabei beliebiger Text sein. Zeitpunkt der letzten Änderung des Quellentextes. Der Quellentext wird nur dann neu übersetzt, wenn sich mtime ändert oder wenn mtime "undef" ist. Datei, in die die Ausgabe geschrieben wird. Ist keine Datei angegeben, wird die Standardausgabe benutzt. Referenz auf einen Skalar, in welchen die Ausgabe geschrieben werden soll. Ein Wert von Null veranlasst Embperl die Seite nicht auszuführen, sondern alle darin enthaltenen Funktionen zu definieren. Dies ist nötig, um sie mittels des sub Parameters der Execute Funktion aufrufen zu können oder als Vorbereitung für einen späteren Import. Ein Wert von Eins veranlasst Embperl die Seite nicht auszuführen, sondern alle darin enthaltenen Funktionen zu definieren und diese in das aktuelle Package zu importieren. Siehe auch "[$ sub $]" Metacommand. Dieser Wert gibt an, ob and wann das "Cleanup" des Packages ausgeführt werden soll. (Siehe auch "Variablen Gültigkeitsbereich und Cleanup") Es wird kein Cleanup ausgeführt. Unter mod_perl wird das Cleanup erst ausgeführt, nachdem die Verbindung zum Client beendet wurde, auch wenn "Execute" mehrfach während eines Request aufgerufen wird. In allen anderen Fällen wird das Cleanup sofort ausgeführt. Cleanup wird sofort ausgeführt. Eine Referenz auf ein Array, um dem aufgerufenen Dokument Parameter zu übergeben. Beispiel: HTML::Embperl::Execute(..., param => [1, 2, 3]) ; HTML::Embperl::Execute(..., param => \@parameters) ; Über das Array @param kann die aufgerufene Seite auf die Parameter zugreifen. Siehe eg/x/Excute.pl aus der Embperl Distribution für ein detailliertes Beispiel. Kann benutzt werden, um die beiden Embperlvariablen @ffld und %fdat zu setzen. Gibt die erste Zeilennummer der Quellendatei an (Default: 1) Wie "EMBPERL_OPTIONS" (siehe unten), außer für Cleanup. HINWEIS: optDisableFormData sollte gesetzt werden, wenn die Formulardaten eines POST Request bereits von der Standardeingabe eingelesen wurden, ansonsten versucht "Execute" die Daten ein zweites Mal einzulesen, was dazu führt, das der Request hängt. Wie "EMBPERL_DEBUG" (siehe unten). Wie "EMBPERL_ESCMODE" (siehe unten). Wie "EMBPERL_PACKAGE" (siehe unten). Wie "EMBPERL_VIRTLOG" (siehe unten). Wenn virtlog gleich uri ist, wird die Embperl Logdatei gesendet. Wie "EMBPERL_ALLOW" (siehe unten) Wie "EMBPERL_PATH" (siehe unten) Die URI des Request. Wird nur für Virtlog Feature benötigt. Wie "EMBPERL_COMPARTMENT" (siehe unten). Wie "EMBPERL_INPUT_FUNC" (siehe unten). Zusätzlich ist es möglich eine Codereferenz anzugeben, die entsprechende Funktion wird dann als Eingabefunktion aufgerufen. Ebenso ist die Angabe einer Arrayreferenz möglich, wobei das erste Element dann die Codereferenz enthält und alle weiteren Elemente als Parameter der Funktion übergeben werden. Wie "EMBPERL_OUTPUT_FUNC" (siehe unten). Zusätzlich ist es möglich eine Codereferenz anzugeben, die entsprechende Funktion wird dann als Ausgabefunktion aufgerufen. Ebenso ist die Angabe einer Arrayreferenz möglich, wobei das erste Element dann die Codereferenz enthält und alle weiteren Elemente als Parameter der Funktion übergeben werden. Wie "EMBPERL_COOKIE_NAME" (siehe unten). Wie "EMBPERL_COOKIE_PATH" (siehe unten). Wie "EMBPERL_COOKIE_DOMAIN" (siehe unten). Wie "EMBPERL_COOKIE_EXPIRES" (siehe unten). Erwartet eine Referenz auf ein Array. Nach der Rückkehr der Funktion enthält das Array alle Fehlermeldungen der aufgerufenen Seite, soweit welche aufgetreten sind. Erwartet einen Dateinamen und liefert eine Hashreferenz zurück, die in das Package der Datei "geblessed" ist, d.h. die Hashreferenze kann dazu genutzt werden, um Funktionen die in der Datei definiert sind, also Methoden aufzurufen. Zusätzlich kann durch den "isa" Parameter (siehe unten) eine Vererbungshierachie zwischen Embperlseiten aufgebaut werden. Außerdem ist es möglich in dem Hash Objektdaten zu speichern. Beispiel: [# Die Datei eposubs.htm definiert zwei Funktionen: txt1 und txt2 #] [# Als erstes erstellen wir ein neues Objekt #] [- $subs = Execute ({'object' => 'eposubs.htm'}) -] [# Nun kann man Methoden aufrufen #] txt1: [+ $subs -> txt1 +] <br> txt2: [+ $subs -> txt2 +] <br> Erwarten den Namen einer Datei und schiebt den Packagename der Datei auf das @ISA Array der aktuellen Seite. Dadurch wird es möglich eine Vererbung zwischen Embperlseiten aufzubauen. Dies ist auch innerhalb von EmbperlObject hilfreich. Beispiel: [! Execute ({'isa' => '../eposubs.htm'}) !] In der Version 1.3.x wird lediglich der Wert 'Text' akzetiert, dieser führt dazu, dass das Verhalten von Embperl 2.0 emuliert wird und der Text lediglich durchgereicht wird und keine Verarbeitung stattfindet.

Hilfsfunktionen für Execute
Diese Funktion dient dazu, die Logdatei sowie die Debugflags, die für die folgenden Aufrufe von "Execute" genutzt werden, zu setzen. Es kann immer nur eine Logdatei existieren, der Pfad kann jedoch jederzeit geändert werden. Durchsucht alle Umgebungsvariablen (%ENV) und setzt %params für die Benutzung von "Execute". Alle Embperl Konfigurationsvariablen, außer EMBPERL_LOG, werden erkannt.

Beispiele für Execute:
# Quellentext steht unter /pfad/zu/seite.html und # das Ergebnis wird in /pfad/zu/ausgabe.html geschrieben HTML::Embperl::Execute ({ inputfile => '/pfad/zu/seite.html', outputfile => '/pfad/zu/ausgabe.html'}) ; # Quellentext steht in einem Skalar und das Ergebnis wird auf der # Standardausgabe ausgegeben # Vergessen Sie nicht, mtime zu ändern wenn $src sich ändert $src = '<html><head><title>Seite [+ $no +]</title></head>' ; HTML::Embperl::Execute ({ inputfile => 'irgendein name', input => \$src, mtime => 1 }) ; # Quellentext steht in einem Skalar und das Ergebnis wird in # einen zweiten Skalar geschrieben my $src = '<html><head><title>Seite [+ $no +]</title></head>' ; my $out ; HTML::Embperl::Execute ({ inputfile => 'anderer name', input => \$src, mtime => 1, output => \$out }) ; print $out ; # Einfügen eines gemeinsammen Kopfes in eine Embperlseite # der sich in /pfad/zu/kopf.html befindet [- Execute ('/pfad/zu/kopf.html') -] Die Runtimekonfiguration wird mittels Umgebungsvariablen eingestellt, entweder auf der Befehlszeile oder in der Webserverkonfigurationsdatei. Die meisten HTTP Server verstehen SetEnv <var> <wert> Wenn Sie Apache und mod_perl nutzen, funktioniert auch PerlSetEnv <var> <wert> Der Vorteil von "PerlSetEnv" gegenüber "SetEnv" ist, daß unterschiedliche Werte für verschiedene Verzeichnisse oder virtuelle Hosts gesetzt werden kann.

EMBPERL_FILESMATCH
Wenn vorhanden, werden von Embperl nur Dateien bearbeitet, die der angegebenen Perl regular expression entsprechen. Alle anderen Dateien werden an den Standard Apachehandler weitergereicht. Dies ist nütztlich, um Embperl Dokumente und Nicht-Embperl Dokumente (z.B. Gifs) in einem Verzeichnis abzulegen. EMBPERL_FILESMATCH funktioniert nur unter mod_perl. Beispiel: # Nur Dateien mit der Endung .htm werden von Embperl bearbeitet PerlSetEnv EMBPERL_FILESMATCH \.htm$

EMBPERL_ALLOW (ab 1.2b10)
Wenn vorhanden, werden von Embperl nur Dateien bearbeitet, die der angegebenen Perl regular expression entsprechen. Die Bearbeitung anderer Dateien wird mit dem Fehlercode FORBIDDEN verweigert. Dies ist vorallem in CGI Mode nützlich, um die Serversicherheit zu erhöhen.

EMBPERL_PATH (ab 1.3b6)
Hier kann eine durch Semikolon (unter Unix auch Doppelpunkte) getrennte Liste von Verzeichnissen angegeben werden, die Embperl durchsucht, wenn eine Datei verabeitet werden soll und der Dateiname keine absolute Pfadangabe enthält und nicht mit "./" (bzw. ".\" unter Windows) anfängt. Verzeichnisse müssen mit einem Slash ("/" bzw. "\") abgeschlossen werden, andernfalls wird der Teil als Dateiprefix interpretiert. Eine spezielle Behandlung findet statt, wenn der Dateiname mit "../" (bzw. "..\") beginnt. Dann wird die selbe Anzahl Elemente wie "../" im Dateinamen sind im Pfad übersprungen.

EMBPERL_COMPARTMENT
Gibt dem Namen des Compartments für die Opcodemaske an. (Siehe "(Sichere-)Namensräume und Opcode Restriktionen" für Details.)

EMBPERL_ESCMODE
Gibt den Anfangswert für "$escmode" an (siehe unten).

EMBPERL_LOG
Pfad für die Embperl Logdatei. Diese enthält Informationen darüber, wie Embperl den eingebetteten Perlcode ausführt. Wieviele Informationen geschrieben werden hängt von der Einstellung der Debugflags ab (siehe "EMBPERL_DEBUG"). Default ist /tmp/embperl.log. HINWEIS: Unter mod_perl muß "EMBPERL_LOG" mittels "PerlSetEnv" gesetzt werden, damit es schon bei Serverstart wahrgenommen wird.

EMBPERL_PACKAGE
Name des Packages in dem der Code ausgeführt wird. Wenn kein Package angegeben ist, erzeugt Embperl für jede Datei einen eindeutigen Packagenamen. Dies verhindert, dass globale Variablen zweier Skripts miteinander in Konflikt geraten.

EMBPERL_VIRTLOG
Gibt eine URI an, unter der die Embperl Logdatei mittels des Browsers abgerufen werden kann. Dieses Feature ist gesperrt, wenn "EMBPERL_VIRTLOG" nicht gesetzt ist. Siehe auch "EMBPERL_DEBUG" und "dbgLogLink" für ein Beispiel, wie dies in Webserverkonfiguration eingestellt werden kann.

EMBPERL_OPTIONS
Diese Bitmaske gibt diverse Optionen für die Ausführung von Embperl an. Damit können bestimmte Features von Embperl gesperrt oder freigegeben sowie das Verhalten von Embperl beeinfluß werden. Um mehrere Optionen anzugeben sind die Werte zu addieren. Cleanup wird nicht nach jedem Request ausgeführt. Führt dazu, dass Embperl im Fehlerfall nicht seine eigene Fehlerseite anzeigt, sondern so viel wie möglich der Seite. Fehler werden lediglich in die Logdatei geschrieben. Ohne diese Option sendet Embperl seine eigne Fehlerseite, die alle Fehler, die aufgetreten sind, anzeigt. Wenn "dbgLogLink" gesetzt ist,werden alle Fehler als Links auf die Logdatei dargestellt. Diese Option hat keinen Effekt, wenn "optReturnError" gesetzt ist. Wenn diese Option gesetzt ist, sendet Embperl keine Fehlerseite, sondern liefert den Fehlercode an Apache oder das aufrufende Programm zurück. Unter Apache ermöglicht dies die "ErrorDocument" Anweisung zu benutzen, um eine eigene Fehlerseite anzuzeigen. Innerhalb des ErrorDokuments ist es möglich die Embperlfehlermeldungen mittels $errors = $req_rec -> prev -> pnotes('EMBPERL_ERRORS') ; zu ermitteln, wobei $errors eine Arrayreferenz ist. (1.3b5+) Veranlasst Embperl den Code in einem sicheren Namensraum auszuführen. Dadurch ist es nicht mehr möglich auf Daten außerhalb des Packages zuzugreifen. (Siehe "(Sichere-)Namensräume und Opcode Restriktionen" für Details.) Veranlasst Embperl eine Operator Maske anzuwenden. Dadurch ist es möglich, bestimmte, unsichere, Opcodes zu sperren. (Siehe "(Sichere-)Namensräume und Opcode Restriktionen" für Details.) Veranlasst Embperl den Quellentext unangetastet zu lassen, lediglich Return-Zeichen werden entfernt, da Perl 5.004 dies nicht akzeptiert. Diese Option sollte aufjeden Fall gesetzt werden, wenn Sie Ihren Quellentext mit einem Ascii Editor schreiben. Wenn Sie jedoch einen (WYSIWYG) HTML-Editor benutzen, welcher unerwünschte HTML Tags in den Perlcode einfügt und spezielle Zeichen HTML-Kodiert (z.B. '<' als &lt;), dann sollten Sie diese Option nicht setzen. Embperl konvertiert dann das HTML automatisch in den Perlcode zurück, wie Sie ihn im Editor eingegeben haben. Normalerweise werden die HTTP Header von Embperl gesendet, nachdem der Request bearbeitet wurde. Dies ermöglicht, während der Bearbeitung des Dokuments beliebige Header zu setzen und Embperl kann den "Content-Length" Header berechnen. Außerdem erzeugt Embperl eine Fehlerseite, statt des Dokuments, falls Fehler auftreten. Um dies zu erreichen, wird die Ausgabe zwischengespeichert bis der Request abgearbeitet wurde, dann werden zuerst die HTTP Header und danach das Dokument gesendet. Dieses Flag führt dazu, das die Header sofort, vor der Ausführung des Dokuments, gesendet werden und die Ausgabe nicht gepuffert ist. Ohne diese Option setzt Embperl das aktuelle Verzeichnis entsprechend dem Verzeichnis, in dem das ausgeführte Skript steht. Dies ermöglicht es innerhalb der Embperlseite relative Pfadnamen zu benutzen. Da der Verzeichniswechsel, u.U. einige Zeit in Anspruch nimmt, kann er mit dieser Option verhindert werden. Diese Option verhindert das Setzen von %fdat und @ffld. Embperl ignoriert die gesendeten Formulardaten vollständig. Wenn gesetzt, verhindet diese Option das Bearbeiten aller HTML Tags vollständig. Embperl sucht dann nur noch nach <[+/-/!/$ ... $/!/-/+]> Blöcken. Dies schaltet dynamische Tabellen, Formularbearbeitung usw. ab. Verhindert die Bearbeitung aller Eingabe Tags. (<INPUT><TEXTAREA><OPTION>) Verhindert die Bearbeitung aller Tabellen Tags. (<TABLE><TH><TR><TD><MENU><OL><UL>) Verhindert die Bearbeitung aller SELECT Tags. (<SELECT>) Verhindert die Bearbeitung aller Meta Tags. (<META HTTP-EQUIV>) Diese Option veranlasst Embperl all Formularfelder in %fdat und @ffld einzufügen, auch wenn sie leer sind. Leere Formularfelder werden als leere Zeichenkette eingefügt. Ohne diese Option werden leere Formularfelder nicht zu %fdat und @ffld hinzufügt. Leitet die Standardausgabe vor jedem Request auf dem Embperlausgabestrom um und setzt sie anschließend zurück. Wenn die Option gesetzt ist kann das normale Perl print benutzt werden, um Ausgaben vorzunehmen. Ansonsten sind Ausgaben nur mittels eines [+ ... +] Blocks oder durch Ausgeben auf die Dateihandle OUT möglich. Normalerweise, wenn Embperl für ein Eingabefeld keinen Wert in %fdat findet, läßt es das HTML Tag unverändert. Mit dieser Option behandelt Embperl das Feld so, als wäre eine leere Zeichenkette in %fdat für dieses Feld, d.h. wenn kein "VALUE" Attribut vorhanden ist fügt Embperl ein "VALUE=""" ein. Mit dieser Option erzeugt Embperl beim Hidden Metacommand keine Hidden-Felder für leere Zeichenketten. Dokumente der Dateilänge Null führen normalerweise zu einem Fehler "NOT_FOUND (404)". Mit dieser Option liefert Embperl ein leeres Dokument zurück. Veranlasst Embperl den Quellencode des Dokuments im Speicher zuhalten. (Der compilierte Perlcode wird immer im Speicher gehalten, unabhänig von diesem Flag). Verhindert das Entfernen von Leerzeilen und Zwischenräumen. Dies ist sinnvoll für Nicht-HTML-Dokumente. Diese Option veranlaßt Embperl die Logdatei zu öffnen, sobald es geladen wird. Dies kann genutzt werden, wenn Embperl unter mod_perl mittels "PerlModule" geladen wird, um die Logdatei als root, statt des nicht-privilegierter Benutzers, zu öffnen. Verhindert das Embperl eine Warnung über nicht abgeschlossene "if", "while", "table", etc. am Dateiende ausgibt.

EMBPERL_DEBUG
Diese Bitmaske gibt an, welche Informationen in die Logdatei geschrieben werden. Um mehrere Optionen anzugeben sind die Werte zu addieren. Minimale Informationen. Speicherverwaltung. Zeigt den Code und das Resultat beim Ausführen von Perl. Schreibt alle Metacommands und HTML Tags, die ausgeführt werden, in die Logdatei. Listet alle Umgebungsvariablen. Listet die an das Dokument gesandten Formulardaten. Zeigt die Bearbeitung von dynamischen Tabellen. Zeigt die Bearbeitung von Eingabefeldern. Führt ein "flush" nach jeder Ausgabe aus. Dies dient lediglich zum Debuggen von Abstürzen und führt normalerweise zu einer deutlichen Verlangsamung der Ausgabe. Führt ein "flush" nach jedem Schreiben in die Logdatei aus. Dies dient lediglich zum Debuggen von Abstürzen und führt normalerweise zu einer deutlichen Verlangsamung der Verarbeitung. Schreibt alle Metacommands und HTML Tags in die Logdatei, unabhänig davon ob sie ausgeführt werden oder nicht. Ein '+' kennzeichnet dabei, dass Embperl diesen Befehl ausführt. Schreibt jeweils den nächsten Teil des Quellencodes in die Logdatei, der ausgeführt wird. (Dadurch kann die Logdatei recht umfangreich werden) Diese Option ist nur verfügbar, wenn Embperl mit "-DEPDEBUGALL" übersetzt wurde. Wenn gesetzt, werden alle Embperl internen Funktionsaufrufe in die Logdatei geschrieben. Dient dem Debuggen von Embperl selbst. Fügt oben auf jeder Seite einen Link ein, der dazu benutzt werden kann, die Logdatei für diesen Request anzuzeigen. Siehe auch "EMBPERL_VIRTLOG". Beispiel: SetEnv EMBPERL_DEBUG 10477 SetEnv EMBPERL_VIRTLOG /embperl/log <Location /embperl/log> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI </Location> Erzeugt jedesmal einen Eintrag in der Logdatei, wenn neuer Perlcode übersetzt wird. Schreibt alle HTTP Header in die Logdatei. Gibt jede Variable, sowie deren Wert, die am Ende des Request "aufgeräumt" wird, aus. Wenn gesetzt, wird für jede Quellencodezeile die Zeit, seit dem Start des Requests, ausgegeben. (dbgSource muß ebenfalls gesetzt sein) Empfangen und Senden von Session cookies wird geloggt. Zeigt, wie Funktionen in andere Packages importiert werden. Ein guter Wert für den Anfang ist 2285 oder 10477. Letzteres ermöglicht das Anzeigen der Logdatei via Browser ("EMBPERL_VIRTLOG" muß ebenfalls gesetzt sein.)

EMBPERL_INPUT_FUNC
Diese Konfigurationsanweisung ermöglicht, statt den Quellentext aus einer Datei zu lesen (oder ihn einem Skalar zu entnehmen), die angegebene Funktion aufzurufen, welche für das Bereitstellen des Quellentextes verantwortlich ist. Die Funktion muß folgendermaßen aussehen: InputFunc ($r, $in, $cacheargs, weitere Parameter...) ; Apache Request Record (siehe perldoc Apache) eine Referenz auf einen Skalar, in welchen der Quellentext abgelegt werden soll. Beispiel: open F, "filename" ; local $\ = undef ; $$in = <F> ; close F ; eine Referenz auf einen Skalar, welcher den Zeitpunkt der letzten Änderungen zurück liefern soll, alternativ kann (ab 1.2.1) eine Hashreferenz mit den Elementen "mtime" und "inputfile" angegeben werden, um das korrekte cachen des vorcompilierten Perlcodes zu ermöglichen. Beispiel: $$cacheargs = -M "filename" ; oder $$cacheargs = { mtime => -M "filename", inputfile => "filename" } ; Es können weitere Parameter (Kommasepariert) in EMBPERL_INPUT_FUNC angegeben werden, welche dann an die Funktion durchgereicht werden. Beispiel: PerlSetEnv EMBPERL_INPUT_FUNC "InputFunc, foo, bar" wird zu folgendem Funktionsaufruf InputFunc ($r, $in, $mtime, 'foo', 'bar') ; Beispiel für eine Funktion, die das gleiche macht wie Embperl: sub Input { my ($r, $in, $mtime) = @_ ; open F, $r -> filename or return NOT_FOUND ; local $\ = undef ; $$in = <F> ; close F ; $$mtime = -M $r -> filename ; return 0 ; } Siehe auch ProxyInput, für eine Funktion die von Embperl bereit gestellt wird. HINWEIS: Es gibt weiterhin zwei Module (HTML::EmbperlChain und Apache::EmbperlFilter) die die Möglichkeit bieten Embperl und andere Module zu verketten.

EMBPERL_OUTPUT_FUNC
Diese Konfigurationsvariable erlaubt das Angeben einer Funktion, die die Ausgabe erledigt. Die Funktion muß folgende Form haben: OutputFunc ($r, $out, weitere Parameter...) ; Apache Request Record (siehe perldoc Apache) Referenz auf einen Skalar, welcher die Ausgabe von Embperl enthält. Es können weitere Parameter (Kommasepariert) in EMBPERL_INPUT_FUNC angegeben werden, welche dann an die Funktion durchgereicht werden. Beispiel: PerlSetEnv EMBPERL_OUTPUT_FUNC "OutputFunc, foo, bar" wird zu folgendem Funktionsaufruf OutputFunc ($r, $out, 'foo', 'bar') ; Beispiel für eine Funktion, die das gleiche macht wie Embperl: sub Output { my ($r, $out) = @_ ; $r -> send_http_header ; $r -> print ($$out) ; return 0 ; } Siehe auch LogOutput, für eine Funktion die von Embperl bereit gestellt wird. HINWEIS: Es gibt weiterhin zwei Module (HTML::EmbperlChain und Apache::EmbperlFilter) die die Möglichkeit bieten Embperl und andere Module zu verketten.

EMBPERL_MAILHOST
Gibt den Rechner an, der von der MailFormTo Funktion als SMTP Server genutzt wird. Default ist localhost.

EMBPERL_MAILHELO (ab 1.3b4)
Gibt den Rechner/die Domain an, der von der MailFormTo Funktion im HELO/EHLO Befehl angegeben wird. Normalerweise setzt Net::SMTP einen sinnvollen Defaultwert ein. In Abhänigkeit von der Installation kann es jedoch manchmal nötig sein diesen Wert von Hand zu setzen.

EMBPERL_MAILFROM (ab 1.2.1)
Gibt die Absender EMail-Adresse an die von der MailFormTo Funktion genutzt wird. Default ist www-server@server_name.

EMBPERL_MAILDEBUG (ab 1.2.1)
Debugeinstellung für Net::SMTP. Default ist 0.

EMBPERL_MAIL_ERRORS_TO (ab 1.2b6)
Wenn hier eine E-Mail Adresse angegeben ist, wird beim Auftreten eines Fehlers, ein E-Mail mit den Fehlermeldungen an diese Adresse versandt.

EMBPERL_SESSION_CLASSES
Hier wird, durch Leerzeichen getrennt, die Klasse für Object Store und Lock Manager (und optional für die Serialisierung und das Generieren der ID) von Apache::Session angegeben (siehe "Session Handling")

EMBPERL_SESSION_ARGS
Liste von zusätzlichen Parametern für Apache::Session Klassen (Leerzeichen getrennt) (siehe "Session Handling"). Argumente die Leerzeichnen enthalten, müssen in Anführungszeichen geschriebene werden. Beispiel: PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=www 'Password=secret word'"

EMBPERL_SESSION_HANDLER_CLASS (ab 1.3b3)
Bestimmt die Klasse die das Session Handling für Embperl durchführt. Default ist "HTML::Embperl::Session". Sie können eine eigene Klasse von HTML::Embperl::Session ableiten und diese hier angeben um Ihr eigenes Session Handling zu implementieren.

EMBPERL_COOKIE_NAME (ab 1.2b4)
Gibt den Namen des Cookies an, das Embperl benutzt, um die Session Id zu senden. Default ist EMBPERL_UID.

EMBPERL_COOKIE_DOMAIN (ab 1.2b4)
Gibt die Domain des Cookies an, das Embperl benutzt, um die Session Id zu senden. Default ist keine Domain.

EMBPERL_COOKIE_PATH (ab 1.2b4)
Gibt den Pfad des Cookies an, das Embperl benutzt, um die Session Id zu senden. Default ist kein Pfad.

EMBPERL_COOKIE_EXPIRES (ab 1.2b4)
Gibt den Ablaufzeitpunkt des Cookies an, das Embperl benutzt, um die Session Id zu senden. Es kann ein vollständiges Datum oder (ab 1.3b5) relative Werte angegeben werden. Beispiele: +30s +10m +1h -1d +3M +10y Default ist kein Ablaufzeitpunkt. Embperl versteht zwei Katagorien von Befehlen. Die erste Kategorie sind spezielle Embperl Befehle, die zweite besteht aus einer Reihe von HTML Tags, die spezielle Funktionen anstoßen. Bevor Embperl Befehle bearbeitet (ebenso für Argumente von HTML Tags, die von Embperl bearbeitet werden), werden alle HTML Tags, die sich innerhalb des Perlcodes befinden, entfernt und HTML kodierte Zeichen werden in ihre Ascii Äquvivalente umgewandelt, so daß sie der Perlinterpreter versteht. Dies ist nötig, um HTML Seiten, die von (WYSIWYG) HTML-Editoren erzeugt werden, zu verarbeiten. (z.B. um ein <BR> innerhalb des Perlcodes zu entfernen, welches der HTML Editor in den Perlcode eingefügt hat, an einer Stelle, wo lediglich ein Zeilenumbruch sein sollte.) Um dieses zu unterbinden, können HTML Tags und HTML kodierten Zeichen (beides nur innerhalb des Perlcodes) ein Backslash ('\') vorangestellt werden. WICHTIGER HINWEIS: Wenn Sie einen Ascii Editor benutzen, um Ihre HTML Dokumente zu schreiben, sollten Sie die Option optRawInput setzen. Dies verhindert das Embperl den Quellentext in der oben beschriebenen Weise vorverarbeitet. Sollten Sie Probleme mit Ihrem Code haben, speziell mit HTML Tags oder Dateihandles, versichern Sie sich, daß Sie die Ein- und Ausgabekodierung und -dekodierung, die Embperl durchführt, verstanden haben. Weitere Hinweise finden sich im Abschnitt "Inside Embperl" und in den FAQs. Alle Embperl Befehle fangen mit einer eckigen Klammer ('[') an und Enden mit der geschlossenen eckigen Klammer (']'). Um eine normale '[' im HTML Text zu erhalten, ist es nötig '[[' zu schreiben. Embperl benutzt keine HTML Kommentare (z.B. <! ... !>) oder andere spezielle HTML Tags, da es mit manchen HTML Editoren nicht, oder nur sehr umständlich, möglich ist, diese zu erzeugen. Da '[' von den HTML Editoren als normaler Text interpretiert wird, sollte es damit keinerlei Probleme geben, es vereinfacht in den meisten Fällen das schreiben der Dokumente erheblich.

[+ Perl Code +]
Ersetzt den Befehl durch das Resultat der Ausführung des Perl codes. "Perl Code" kann dabei beliebiger Perl code sein. Beispiel: [+ $a +] Ersetzt [+ $a +] mit dem Inhalt der Variablen $a. [+ $a+1 +] Beliebige Ausdrücke können benutzt werden. [+ $x[$i] +] Auch Arrays, Hashs oder komplexere Ausdrücke sind kein Problem HINWEIS: Leerzeichen werden ignoriert. Die Ausgabe wird automatisch HTML kodiert (z.B. wird '<' zu '&lt;'). Die Ausgabekodierung kann mit der Variablen $escmode gesteuert werden.

[- Perl Code -]
Führt den "Perl Code" aus. In der Ausgabe wird dieser Befehl jedoch vollständig entfernt. Beispiel: [- $a=1 -] Setzt die Variable $a auf 1. [- use SomeModule -] Andere Perlmodule können genutzt werden. [- $i=0; while ($i<5) {$i++} -] Auch komplexer Code kann verwendet werden. HINWEIS: Perlbefehle, wie "if", "while", "for", etc., müssen innerhalb eines Embperl Blockes abgeschlossen werden. Es ist nicht möglich das "if" in einem Block zu schreiben und die abschließenden Klammer ('}') in einem anderen Block. Dies ist nur mit "[* Perl Code *]" Blöcken möglich. HINWEIS: Um Perlfunktionen zu definieren, benutzen Sie "[! Perl Code !]" (siehe unten) da dies vermeidet, dass die Funktion bei jedem Aufruf neu übersetzt wird.

[! Perl Code !]
Wie "[- Perl Code -]" wird aber nur beim ersten Aufruf des Dokuments ausgeführt. Dies kann genutzt werden, um Perlfunktionen zu definieren oder einmalige Initialisierungen auszuführen.

[* Perl Code *]
(ab 1.2b2) Ähnlich wie ""[- Perl Code -]"". Der Hauptunterschied ist, daß "[- Perl Code -]" Blöcke immer ihren eigenen Gültigkeitsbereich haben, während "[* Perl Code *]" Blöcke im selben Gültigkeitsbereich ablaufen. Dies ermöglicht lokale Variablen (mit "local") mit einem Gültigkeitsbereich, der die ganze Seite umfasst, zu definieren. Normalerweise ist es nicht nötig lokale Variablen zu definieren, da Embperl jedem Dokument einen eigenen Namensraum zuordnet und die globalen Variablen nach jedem Request wieder aufgeräumt werden. In speziellen Fällen (z.B. um eine Embperl Seite rekursiv mittes Execute aufzurufen), ist es jedoch hilfreich. Ein zweiter Grund ist, die Möglichkeit Perlbefehle zu nutzen, die sich über mehrere Blöcke hinziehen. Perls "if", "while", "for", etc. können sich nicht über mehrere ""[- Perl Code -]"" Blöcke hinziehen, jedoch sehr wohl über mehrere ""[* Perl Code *]"" Blöcke. Beispiel: [* foreach $i (1..10) { *] [- $a = $i + 5 -] Schleifenzähler + 5 = [+ $a +] <br> [* } *] Folgendes hingegen funktioniert nicht: [- foreach $i (1..10) { -] irgendwelcher Text <br> [- } -] Der selbe Effekt kann mit Embperl Meta Commands erzielt werden (siehe unten) [$ foreach $i (1..10) $] [- $a = $i + 5 -] Schleifenzähler + 5 = [+ $a +] <br> [$ endforeach $] HINWEIS 1: "[* ... *]" Blöcke müssen immer mit ;,{ oder } enden! HINWEIS 2: "[* ... *]" Blöcke können nicht innerhalb eines HTML Tags, welches von Embperl interpretiert wird, verwendet werden. (Außer die Bearbeitung des entsprechden Tags wurde ausgeschaltet) HINWEIS 3: Da die Ausführung von "[- ... -]" Blöcken durch Embperl gesteuert wird, kann Embperl deutlich detailliertere debugging Ausgaben in der Logdatei dafür erzeugen. Außerdem existieren für "[- ... -]" keinerlei Restriktionen, wo sie genutzt werden können.

[# Text #]  (Kommentar)
(ab1.2b2) Dies ist ein Kommentarblock. Alles zwischen "[#" und "#]" wird aus dem HTML Dokument entfernt, bevor es zum Browser gesandt wird. HINWEIS 1: "[* ... *]" Blöcke werden vor Kommentarblöcken ausgewertet, deshalb werden sie auch innerhalb von Kommentarblöcken ausgeführt. HINWEIS 2: Alles innerhalb des Komentarblocks (außer "[* ... *]") wird aus dem Quellentext entfernt, deshalb ist es möglich, Teile des Dokuments damit auszukommentieren.

[$ Cmd Arg $]  (Meta-Commands)
Ausführen eines Embperl Meta-Commands. Cmd kann einer der folgenden Befehle sein: (Arg variiert, je nach Befehl). Alles nach dem if Meta-Command bis zum else, elsif oder endif wird nur ausgegeben, wenn der Perlausdruck, welcher durch Arg gegeben ist, wahr ist. else und elsif funktionieren entsprechend. Beispiel: [$ if $ENV{REQUEST_METHOD} eq 'GET' $] Methode ist GET<BR> [$ else $] Andere Methode als GET wurde benutzt<BR> [$ endif $] Dieses Beispiel sendet einen der zwei Sätze zum Browser, in Abhänigkeit davon, ob die GET-Methode benutzt wurde, um dieses Dokument abzurufen. Führt eine Schleife aus, bis Arg des while Befehls falsch ist. Beispiel: (siehe auch eg/x/loop.htm aus der Embperl Distribution) [- $i = 0; @k = keys %ENV -] [$ while ($i &lt; $#k) $] [+ $k[$i] +] = [+ $ENV{$k[$i]} +]<BR> [- $i++ -] [$ endwhile $] Dies sendet alle Umgebungsvariablen zum Browser. HINWEIS: '&lt;' wird zu '<' bevor es vom Perlinterpreter ausgeführt wird, außer optRawInput ist gesetzt. Führt eine Schleife aus, bis Arg des until Befehls wahr ist. Beispiel: [- $i = 0 -] [$ do $] [+ $i++ +] <BR> [$ until $i > 10 $] Führt eine Schleife aus, für jedes Element des Array, welches als zweites in Arg steht, wobei die Variable, die als erstes in Arg angegeben ist, auf den entsprechenden Wert gesetzt wird. Beispiel: [- @arr = (1, 3, 5) -] [$ foreach $v @arr $] [+ $v +] <BR> [$ endforeach $] Arg gibt keinen, einen oder zwei Hashs an (mit oder ohne führendes '%' Zeichen) und ein optionales Array als dritten Parameter. "hidden" erzeugt versteckte Eingabefelder für alle Werte, die im ersten Hash, jedoch nicht im zweiten Hash, enthalten sind. Default ist %fdat und %idat. Wenn der dritte Parameter angegeben ist, gibt er die Reihenfolge der Felder an. Default ist @ffld. Wenn Sie keine Parameter angeben, erzeugt Embperl für alle Werte, die an dieses Dokument geschickt wurden (in %fdat stehen), verstecke Eingabefelder, soweit dafür nicht schon andere Eingabefelder existieren. Dies ist nützlich, um Werte zwischen mehreren Formularen zu transportieren. Beispiel: (siehe auch eg/x/input.htm aus der Embperl Distribution) <FORM ACTION="inhalt.htm" METHOD="GET"> <INPUT TYPE="TEXT" NAME="field1"> [$ hidden $] </FORM> Wenn Sie dieses Dokument mit http://host/doc.htm?field1=A&field2=B&field3=C aufrufen, erzeugt Embperl folgende Ausgabe: <FORM ACTION="inhalt.htm" METHOD="GET"> <INPUT TYPE="TEXT" NAME="feld1" VALUE="A"> <INPUT TYPE="HIDDEN" NAME="field2" VALUE="B"> <INPUT TYPE="HIDDEN" NAME="field3" VALUE="C"> </FORM> Das "var" Meta-Command definert eine oder mehrere Variablen zur Benutzung innerhalb dieser Embperlseite und setzt das strict Pragma. Die Variablennamen müssen durch Leerzeichen getrennt werden. Beispiel: [$var $a %b @c $] Dies entspricht dem folgendem Perl code: use strict ; use vars qw($a %b @c) ; HINWEIS: 'use strict' innerhalb eines Embperl Dokuments gilt nur innerhalb des Blockes, in dem es erscheint. (ab Embperl 1.2b5) Definiert eine Embperl-Funktion. Beispiel: [$ sub foo $] <p> Hier steht was </p> [$ endsub $] Diese Funktion kann entweder als normale Perlfunktion aufgerufen werden: [- foo -] oder mittels der HTML::Embperl::Execute Funktion. [- Execute ('#foo') # Kurzform -] [- Execute ({ sub => 'foo'}) # Langform -] Der Unterschied ist, das Embperl nach dem Aufruf einer Embperl-Funktion mittels "Execute", die internen Zustände (Optionen, Debugflags etc.) wieder auf die Werte vor dem Aufruf zurücksetzt. Außerdem ist es möglich mittels "Execute" rekursive Funktionsaufrufe zu implementieren. Es ist ebenfalls möglich Parameter an eine Embperl-Funktion zu übergeben: [$ sub foo $] [- $p = shift -] <p> Hier zeigen wir den ersten Parameter [+ $p +]</p> [$ endsub $] [- foo ('value') -] Wenn Sie eine Reihe von oft benötigten Funktionen haben, können Sie sie in einer Embperl Datei definieren und in Ihre Dokumente importieren: [- Execute ({ inputfile => 'mylib.htm', import => 1 }) -] Dies importiert alle Embperl-Funktionen, die in der Datei mylib.htm definiert sind, in die aktuelle Seite, wo sie dann als normale Perlfunktionen aufgerufen werden können.

HTML Tags
Embperl behandelt die folgenden HTML Tags speziell. Embperl kann dynamische Tabellen erzeugen (ein- oder zweidimensional). Dazu ist es lediglich nötig, eine Zeile oder Spalte anzugeben, Embperl expandiert die Tabelle so weit wie nötig. Dies geschieht durch die Benutzung der "magischen" Variablen $row, $col oder $cnt. Solange Sie nicht eine der drei Variablen innerhalb einer Tabelle benützen, läßt Embperl die Tabelle unverändert. Embperl überprüft ob $row, $col oder $cnt benutzt werden und wiederholt allen Text zwischen <TABLE> und </TABLE>, solange der Block in dem $row oder $cnt enthalten sind, ein Ergebnis ungleich undef zurück gibt. Aller Text zwischen <TR> und </TR> wird wiederholt, wenn die Variable $col benutzt wird und der Block, indem sie vorkommt, einen definierten Rückgabewert hat. Rückgabewert ist dabei immer das Ergebnis des letzten Ausdrucks innerhalb des Blocks. Mittels $tabmode (siehe unten) kann das Tabellenendekriterium variiert werden. Beispiel: (siehe eg/x/table.htm in der Embperl Distribution für weitere Beispiele) [- @k = keys %ENV -] <TABLE> <TR> <TD>[+ $i=$row +]</TD> <TD>[+ $k[$row] +]</TD> <TD>[+ $ENV{$k[$i]} +]</TD> </TR> </TABLE> Der obige Code zeigt alle Elemente des Array @k (das die Schlüssel von %ENV enthält) an, so dass alle Umgebungsvariablen (wie im Beispiel zu while) angezeigt werden. Dabei enthält die erste Spalte den Index (ab Null zählend), die zweite Spalte den Variablennamen und die dritte Spalte den Wert der Umgebungsvariablen. Das <TH> Tag wird als Tabellenüberschrift interpretiert. Wenn die ganze Zeile aus <TH> und </TH>, statt aus <TD> und </TD> besteht, werden die Zellen als Spaltenüberschriften interpretiert und nur einmal ausgegeben. Listen, Menüs und Listboxen werden genau wie eindimensionale Tabellen behandelt. Nur "$row", "$maxrow", "$col", "$maxcol" und "$tabmode" werden beachtet, $col und $maxcol werden ignoriert. Siehe auch eg/x/lists.htm aus der Embperl Distribution für ein Beispiel. Embperl prüft ob ein Wert für die entsprechende Option in den Formulardaten (%fdat) vorhanden ist. Wenn ja wird die Option als ausgewählt angezeigt. Beispiel: <FORM METHOD="POST"> <P>Select Tag</P> Wenn Sie dieses Dokument mit list.htm?SEL1=x aufrufen, können Sie die Option bestimmen, die angewählt erscheint. <P><SELECT NAME="SEL1"> <OPTION VALUE="[+ $v[$row] +]"> [+ $k[$row] +] </OPTION> </SELECT></P> </FORM> Das "INPUT" Tag arbeitet mit den Hashs %idat und %fdat zusammen. Wenn das "INPUT" Tag kein "VALUE" Attribute hat, jedoch in %fdat ein Element, das dem "NAME" Attribute entspricht, existiert, erzeugt Embperl ein "VALUE" Attribute mit dem Wert aus %fdat. Alle Werte der "INPUT" Tags werden in dem Hash %idat, mit dem Namen des "INPUT" Tags als Schlüssel und ihrem Wert, gespeichert. Für Radiobuttons und Checkboxen ("TYPE=RADIO" und "TYPE=CHECKBOX"), wird das "CHECKED" Attribute eingefügt, wenn der Wert des "VALUE" Attributes mit dem Wert in %fdat übereinstimmt, andernfalls wird "CHECKED" entfernt. Das bedeutet, wenn Sie die Formulardaten an das Dokument selbst schicken (die URL des "ACTION" Attributes entspricht dem aktuellen Dokument oder fehlt ganz), zeigen alle "INPUT" Tags automatisch die selben Werte an, die der Benutzer vor dem Absenden eingegeben hat. Das "TEXTAREA" Tag wird genau wie ein normales "INPUT" Tag behandelt (siehe oben) "META HTTP-EQUIV= ... " überschreibt den entsprechenden HTTP Header. Dies verhindert, das Netscape nachfragt, ob das Dokument neu geladen werden soll, wenn der Content-Type zwischen "META HTTP-EQUIV" und HTTP Header unterschiedlich ist. Dies kann ebenfalls benutzt werden, um beliebige HTTP Header zu setzen. Unter mod_perl können HTTP Header auch mit der Funktion "header_out" gesetzt werden. Beispiel: <META HTTP-EQUIV="Language" CONTENT="DE"> Das entspricht der Apachefunktion: [- $req_rec ->  header_out("Language" => "DE"); -] Die Ausgaben von Perlblöcken innerhalb des "HREF" Attributes des "A" Tags und des "SRC" Attributes der anderen Tags werden URL Kodiert, statt HTML Kodiert. (siehe auch $escmode). Des weiteren expandiert Embperl Array- und Hashreferenzen innerhalb solcher URLs zur URL Parametersyntax. Beispiel: [- $A = {A => 1, B => 2} ; # Hashreference @A = (X, 9, Y, 8, Z, 7) -] <A HREF="http://localhost/tests?[+ $A +]"> <A HREF="http://localhost/tests?[+ \@A +]"> wird von Embperl zu Folgendem expandiert: <A HREF="http://localhost/tests?A=1&B=2"> <A HREF="http://localhost/tests?X=9&Y=8&Z=7"> Der Gültigkeitsbereich von Variablen, die mit "my" oder "local" deklariert wurden, endet am Ende des umschließenden "[+/- ... -/+]" Blocks. Der "[+/- ... -/+]" Block verhält sich in dieser hinsicht wie Perls "{ ... }". Globale Variablen (alles was nicht mittels "my" oder "local" deklariert wurde) werden am Ende jedes Request automatisch wieder gelöscht (insofern verhalten sie sich wie Variablen, deren Gültigkeitsbereich das gesamte Dokument ist). Dies verhindert Probleme mit Variablen, die ihren Wert aus dem vorangegangenen Request behalten haben. Das Cleanup wird nur für Variablen innerhalb des Packages, der gerade ausgeführten Embperlseite, durchgeführt, d.h. alle Variablen die ohne expliziten Packagenamen deklariert wurden. Alle Variablen in anderen Packages (z.B. andere Perl Module) bleiben gültig. Der Packagename der aktuellen Seite wird normalerweise von Embperl eindeutig vergeben, kann aber mittels EMBPERL_PACKAGE explizit angegeben werden. Da CGI Skripte sowieso immer als eigenständiger Prozeß ausgeführt werden, ist ein Cleanup bei CGI Skripten nicht nötig. Sollen Variablen nicht am Ende des Request aufgeräumt werden, müssen sie entweder im Hash %CLEANUP (mit Wert 0) eingetragen sein oder innerhalb eines anderen Packages (z.B. $Persistent::handle) deklariert werden. Wenn Sie das "strict" Pragma ("use strict") nutzen wollen, können sie Ihre Variablen mittels des "var" Meta-Commands deklarieren. HINWEIS: Da Apache::DBI, wie jedes andere Perlmodul, seinen eigenen Namensraum hat, funktioniert es ohne Problem zusammen mit Embperl. Das automatische Cleanup kann mittels EMBPERL_OPTIONS bzw. dem cleanup Parameter der Execute Funktion abgeschaltet werden. Ausnahmen für Variablen, die nicht oder zusätzlich aufgeräumt werden sollen, können mittels des Hash %CLEANUP angegeben werden. Es ist ebenfalls möglich eine Funktion aufrufen zulassen, wenn Embperl sein Cleanup durchführt. Soweit definiert, wird die Funktion CLEANUP aufgerufen, direkt bevor die weiteren Variablen aufgeräumt werden. Beispiel: [! sub CLEANUP { $obj -> term ; } !] Embperl hat einige spezielle Variablen mit einer vorgegebenen Bedeutung.

%ENV
Enthält die selben Umgebungsvariablen, wie bei einem CGI Skript.

%fdat
Enthält alle Formulardaten, die an das Dokument gesendet wurden. Das "NAME" Attribute bildet den Schlüssel und das "VALUE" Attribute den Wert des Hashelements. Dabei ist es egal, ob die Daten mittels "GET" oder "POST" übetragen wurden. Existieren mehrere Werte mit dem selben Namen, werden diese mittels "TAB" getrennt. Diese können z.B. mittels folgenden Code in ein Array zerlegt werden: @array = split (/\t/, $fdat{'fieldname'}) ; Embperl unterstützt ebenfalls den Kodierungstyp multipart/form-data, der für Dateiuploads benutzt wird. Das Element in %fdat enthält dann eine Dateihandle (entsprechend CGI.pm), die benutzt werden kann, um die Datei auszulesen. Dateiupload Beispiel: HTML Formular: <FORM METHOD="POST" ENCTYPE="multipart/form-data"> <INPUT TYPE="FILE" NAME="ImageName"> </FORM> Embperl ACTION: [- if (defined $fdat{ImageName}) { open FILE, "> /tmp/file.$$"; print FILE $buffer while read($fdat{ImageName}, $buffer, 32768); close FILE; } -] Wenn CGI.pm 2.46 oder höher installiert ist, ist es weiterhin möglich den Dateinamen (den lokalen Dateinamen, wie er auf seiten des Browsers heißt) und Informationen, die von der CGI.pm Funktion "uploadInfo" zur Verfügung gestellt werden, zu erhalten. Der Dateiname ist in dem entsprechenden %fdat Element direkt enthalten. Um auf die uploadInfos zuzugreifen, muß man dem Feldnamen einen Bindestrich voranstellen: Beispiel: # ImageName ist der NAME des Feldes. # Er durch den im HTML Code angegeben ersetzt werden. Dateiname: [+ $fdat{ImageName} +] <br> Content-Type: [+ $fdat{-ImageName} -> {'Content-Type'} +] <br> HINWEIS: Der Zugriff auf die Upload-Infos erfolgte vor 1.2b11 auf andere Art und Weise, die nicht mehr unterstützt wird. HINWEIS: Dies funktioniert ebenfalls in die andere Richtung. Bei Inputtags deren Name einem %fdat Schlüssel entspricht und die kein Value Attribute haben wird automatisch der Wert aus %fdat als Value eingesetzt. Siehe "HTML Tags" "INPUT/OPTION/TEXTAREA".

@ffld
Enthält alle Formularfeldnamen in der Reihenfolge, wie sie vom Browser geschickt wurden. Dies entspricht normalerweise der Reihenfolge, wie sie im Formular erscheinen.

%idat
Enthält alle Werte von allen "INPUT", "TEXTAREA" und "SELECT/OPTION" Tags, die in der Seite vorangehen.

%udat (ab 1.2b1)
Sie können %udat benutzen, um Daten pro Benutzer zu speichern. Solange Sie nicht auf %udat zugreifen passiert gar nichts, sobald jedoch Daten in %udat geschrieben werden, erzeugt Embperl eine Session Id und sendet sie mittels eines Cookies zum Browser. Die Daten die in %udat abgelegt wurden, werden mittels Apache::Session gespeichert. Wenn der selbe Benutzer die nächste Embperl Seite aufruft, sendet der Browser den Cookie mit der Session Id zurück und Embperl stellt die Daten in %udat wieder her. (siehe auch Abschnitt über "Session Handling")

%mdat (ab 1.2b2)
%mdat speichert Daten je Seite. Solange Sie nicht auf %mdat zugreifen passiert gar nichts, sobald jedoch Daten in %mdat geschrieben werden, erzeugt Embperl eine Seiten Id und speichert die Daten mittels Apache::Session. Wenn ein Benutzer die selbe Embperl Seite aufruft, stellt Embperl die Daten in %mdat wieder her. (siehe auch Abschnitt über "Session Handling")

$row, $col
Reihen und Spaltenzähler für dynamische Tabellen. (Siehe "HTML Table Tag".)

$maxrow, $maxcol
Maximale Anzahl von Reihen oder Spalten einer dynamischen Tabelle. Diese Werte werden per default auf 100 für $maxrow und 10 für $maxcol gesetzt um Endlosschleifen zuverhindern. (Siehe "HTML Table Tag".)

$cnt
Enthält die Anzahl der Tabellenzellen, die bis jetzt angezeigt wurden. (Siehe "HTML Table Tag".)

$tabmode
Entscheidet, wann das Tabellenende erreicht ist. Dynamische Tabellen werden immer durch $maxrow und $maxcol begrenzt. Zusätzlich können folgende Bedinungen für das Tabellenende festgelegt werden: Ende, wenn ein Block der $row enthält, "undef" als Ergebnis hat. Die Reihe, die den undefinierten Ausdruck enthält, wird nicht mehr angezeigt. Ende, wenn ein Block der $row enthält, "undef" als Ergebnis hat. Die Reihe, die den undefinierten Ausdruck enthält, wird angezeigt. Ende, wenn $maxrow Reihen angezeigt wurden. Spaltenende: Ende, wenn ein Block der $col enthält, "undef" als Ergebnis hat. Die Spalte, die den undefinierten Ausdruck enthält, wird nicht mehr angezeigt. Ende, wenn ein Block der $col enthält, "undef" als Ergebnis hat. Die Spalte, die den undefinierten Ausdruck enthält, wird angezeigt. Ende, wenn $maxcol Spalten angezeigt wurden. Der Defaultwert von 17 ist korrekt zum Anzeigen von Arrays. Es dürfte selten nötig sein diesen Wert zu ändern. Die Werte für Tabellen- und Spaltenende können addiert werden.

$escmode
Schaltet die HTML und URL Kodierung der Ausgabe ein und aus. Default ist ein ($escmode = 3). Hinweis: Normalerweise kann die Kodierung durch Voranstellen eines Backslashes ('\') vor das entsprechende Zeichen verhindert werden. Das ist recht nützlich, ist aber in Situation, wo eine Benutzereingabe nochmal angezeigt wird, sehr gefährlich, da dies dem Benuter ermöglich beliebiges HTML einzugeben. Um dies zu verhindern muß zu den unten aufgeführten Werten jeweils eine 4 addiert werden. Dies führt dazu, dass Embperl den Backslash bei der Ausgabe nicht gesondert behandelt. (ab 1.3b4) Hinweis 2:Um binäre Daten auszugeben muß escmode auf Null gesetzt werden (ab 1.3b6) Das Resultat von Perlausdrücken wird HTML Kodiert (z.B. '>' wird zu '&gt;') und URL Kodiert ('&' wird zu '%26') innerhalb von "A", "EMBED", "IMG", "IFRAME", "FRAME" und "LAYER" Tags. Das Resultat von Perlausdrücken wird immer URL Kodiert ('&' wird zu '%26'). Das Resultat von Perlausdrücken wird immer HTML Kodiert (z.B. '>' wird zu '&gt;'). Keine HTML oder URL Kodierung findet statt.

$req_rec
Diese Variable ist nur vorhanden, wenn Embperl unter mod_perl läuft und enthält eine Referenz auf den Apache Request Record. Damit ist es möglich, alle Apache internen Funktionen zu nutzen. (siehe perldoc Apache für weitere Informationen)

LOG
Dies ist die Dateihandle der Embperl Logdatei. Durch schreiben auf diese Dateihandle ist es möglich, Zeilen in die Embperl Logdatei zu schreiben. Beispiel: print LOG "[$$]ABCD: your text\n" ; Wenn Sie ein Modul schreiben, das ebenfalls die Embperl Logdatei nutzen soll, können Sie folgendermaßen eine Dateihandle dafür bekommen: tie *LOG, 'HTML::Embperl::Log';

OUT
Diese Dateihandle ist an den Embperl Ausgabestrom gebunden. Ausgaben an diese Handle haben den selben Effekt wie ein "[+ ... +]" Block. (Siehe auch optRedirectStdout)

@param
Wird durch den "param" Parameter der "Execute" Funktion gesetzt. Kann genutzt werden, um Parameter an ein Embperl Dokument zuübergeben oder zurückzugegben. (siehe Execute)

%http_headers_out (ab 1.2b10)
Dieser Hash ermöglicht es HTTP Header anzugeben, die Embperl vor dem Dokument senden soll. Ist ein "Location" Header angegeben, setzt Embperl den Status automatisch auf 301. Beispiel: [- $http_headers_out{'Location'} = "http://www.ecos.de/embperl/" -] Ab 1.3.2 können alle HTTP Header (außer "Location" und "Content-Type") auch mehrere Werte erhalten. Um z.B. mehrere Cookie zu setzen, kann man folgendes schreiben: [- $http_headers_out{'Set-Cookie'} = ['name=cook1;value=2;','name=cook2;value=b'] ; -] Für "Location" und "Content-Type" wird nur der erste Wert berücksichtigt. Leere Arrays werden ignoriert. Z.B. führt Folgendes nicht zu einem Redirect: [- $http_headers_out{'Location'} = [] ; -] siehe auch "META HTTP-EQUIV= ..."

$optXXX $dbgXXX
Alle Optionen (see "EMBPERL_OPTIONS") und alle Debugflags (siehe "EMBPERL_DEBUG") können durch entsprechende Variablen innerhalb der Seite gelesen und gesetzt werden. Beispiel: [- $optRawInput = 1 -] # Anschalten von RawInput [- $optRawInput = 0 -] # Abschalten von RawInput [+ $dbgCmd +] # Ausgeben des Zustandes des dbgCmd Flags Es gibt einige Ausnahmen, bei denen die Optionen lediglich gelesen werden können. Das Setzen solcher Optionen ist nur in den Konfigurationsdateien möglich. Folgende Optionen können nur gelesen werden:

%CLEANUP
Embperl räumt nur Variablen auf, die innerhalb der Embperl Seite definiert wurden. Sollen weitere Variablen aufgeräumt werden, können diese dem Hash %CLEANUP, mit dem Variablennamen als Schlüssel und einem Wert von 1, hinzugefügt werden. Umgedreht ist es möglich das Aufräumen zu verhindern, wenn der Variablennamen mit einem Wert von 0 hinzugefügt wird.

%CLEANUPFILE (ab 1.2b6)
Hat die selbe Aufgabe wie %CLEANUP, jedoch können hier Dateinamen hinzugefügt werden und alle Variable die in diesen Dateien definiert wurden, werden am jedes des entsprechenden Requests aufgeräumt. Embperl ist in der Lage, Daten pro Benutzer für Sie zu verwalten. Sobald Sie Daten in den Hash %udat schreiben, sorgt Embperl dafür, dass die selben Daten wieder verfügbar sind, sobald der selbe Benutzer eine weitere Seite aufruft. Weiterhin können Sie Daten in dem Hash %mdat ablegen, diese sind der aktuellen Seite zugeordnet und werden wieder hergestellt, sobald ein beliebiger Benutzer die selbe Seite aufruft. Im Gegensatz zu einfachen globalen Variablen, ist der Zugriff auf die Inhalte von %udat und %mdat bei entsprechender Konfiguration, auch über Prozeß- oder sogar Rechnergrenzen hinweg möglich. Embperl bedient sich dazu des Perlmodules Apache::Session. Um das Session Management zu aktivieren muß Apache::Session (Version 1.00 oder höher) installiert sein. Außerdem müssen Sie Embperl, via "EMBPERL_SESSION_CLASSES", mitteilen, welcher Speicher- und Lockingmechanismus genutzt werden soll, ggf. müssen Sie auch weitere Argumente für Apache::Session setzen. Um z.B. eine MySQL Datenbank zur Speicherung der Sessions zu benutzen, könnte die Datei startup.pl folgendermaßen aussehen: BEGIN { $ENV{EMBPERL_SESSION_CLASSES} = "MySQL Semaphore" ; $ENV{EMBPERL_SESSION_ARGS} = "DataSource=dbi:mysql:session UserName=test" ; } ; use HTML::Embperl ; Dass selbe kann stattdessen auch direkt in die httpd.conf eingetragen werden: PerlSetEnv EMBPERL_SESSION_CLASSES "MySQL Semaphore" PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=test" PerlModule HTML::Embperl ; Konsultieren Sie die Dokumentation von Apache::Session (in diesem Fall Apache::Session::Store::MySQL) für Informationen wie die Datenbanktabellen dazu aussehen müssen. "EMBPERL_SESSION_ARGS" ist eine Leerzeichen separierte Liste von Name/Wert Paaren die zusätzlich Parameter für die Apache::Session Klassen angeben können. Hier ist ein weiteres Beispiel für die Speicherung der Sessiondaten im Dataisystem: PerlSetEnv EMBPERL_SESSION_CLASSES "File Semaphore" PerlSetEnv EMBPERL_SESSION_ARGS "Directory=/path/to/your/sessions" Konsultieren Sie die Dokumentation von Apache::Session um zu erfahren welche weiteren Speichermöglichkeiten es gibt. Zusätzlich (optional) zur zur Speicher- und Lockingklasse können in "EMBPERL_SESSION_CLASSES" zwei weitere Klassen angegeben werden. Die erste ist für die Serialisierung der Daten zuständig (Default: "Storable") und die zweite für sas erzeugen der ID (Default: "MD5"). HINWEIS: Die obige Konfiguration funktioniert nur mit Apache::Session 1.52 und Embperl 1.3b5 oder höher. Ältere Konfigurationen mit Apache::Session werden weiterhin unterstützt, Ältere Versionen von Embperl unterstützen nur Apache::Session 1.0x, welches eine andere Konfiguartion von $ENV{EMBPERL_SESSION_CLASSES} erfordert (z.B. "$ENV{EMBPERL_SESSION_CLASSES} = "DBIStore SysVSemaphoreLocker" ; "). Damit ist das Session Handling eingerichtet und der Benutzung der Hashs %udat und %mdat steht nichts mehr im Wege. Dabei wird das Session Handling nur dann aktiv, wenn Sie auf einen der zwei Hashs zugreifen. Beim ersten Zugriff erzeugt Embperl bzw. Apache::Session eine Session ID. Für Benutzerbezogene Session wird diese Id mittels eines Cookies zum Browser gesandt. Außerdem veranlasst Embperl Apache::Session die Daten zu speichern. Empfängt Embperl einen solchen Cookie mit einer Id, wird diese zunächst nur abgespeichert, erst bei einem Zugriff auf %udat, werden die Daten tatsächlich von Apache::Session angefordert. Ebenso werden die Daten für %mdat erst von Apache::Session angefordert, wenn auf diesen Hash zugegriffen wird.

Funktionen/Methoden fürs Session Handling

HTML::Embperl::Req::SetupSession ($req_rec, $Inputfile) [1.3b6+]
Diese Funktion kann von Skripten benutzt werden die in ihrem Verlauf HTML::Embperl::Execute aufrufen, jedoch vorher schon auf die Sessiondaten von Embperl zugreifen wollen. Apache request record soweit das Skript unter mod_perl läuft, ansonsten "undef". Name der Datei die später von Embperl bearbeitet werden soll. Dient dazu %mdat zu initialsieren. Wird %mdat nicht benötigt, kann dieser Parameter weggelassen werden. Liefert eine Referenz auf %udat oder, wenn es in einem Arraykontext aufgerufen wird, eine Referenz auf %udat und %mdat zurück. Siehe auch "CleanupSession".

HTML::Embperl::Req::GetSession / $r -> GetSession [1.3b6+]
Liefert eine Referenz auf %udat oder, wenn es in einem Arraykontext aufgerufen wird, eine Referenz auf %udat und %mdat zurück. Dies Funktion kann benutzt werden um auf die Embperl Sessiondaten aus einem Modul zuzugreifen, wenn das Session Handling bereits initialisiert ist. Wenn es als eine Methode aufgerufen wird muß $r ein "HTML::Embperl::Req" Objekt sein. Dieses wird als erster Parameter in @_ an jede Seite übergeben.

HTML::Embperl::Req::CleanupSession / $r -> CleanupSession [1.3b6+]
Muß am Ende jedes Skripts aufgerufen werden, welches "SetupSession" benutzt, danach aber nicht HTML::Embperl::Execute aufruft. Wenn es als eine Methode aufgerufen wird muß $r ein "HTML::Embperl::Req" Objekt sein. Dieses wird als erster Parameter in @_ an jede Seite übergeben.

HTML::Embperl::Req::DeleteSession / $r -> DeleteSession [1.3b6+]
Löscht die Sessiondaten und entfernt den Cookie vom Browser. Wenn es als eine Methode aufgerufen wird muß $r ein "HTML::Embperl::Req" Objekt sein. Dieses wird als erster Parameter in @_ an jede Seite übergeben.

HTML::Embperl::Req::RefreshSession / $r -> RefreshSession [1.3b6+]
Stößt das nochmalige senden des Cookies an. Normalerweise wird der Cookie nur beim ersten Mal gesendet. Wenn es als eine Methode aufgerufen wird muß $r ein "HTML::Embperl::Req" Objekt sein. Dieses wird als erster Parameter in @_ an jede Seite übergeben.

HTML::Embperl::Req::SetSessionCookie / $r -> SetSessionCookie [1.3b7+]
Muß von Skripts aufgerufen werden, welches "SetupSession" benutzen, danach aber nicht HTML::Embperl::Execute aufrufen, um den Cookie für sie Session-Id zu setzen. Dies wird normalerweise durch HTML::Embperl::Execute erledigt. Wenn es als eine Methode aufgerufen wird muß $r ein "HTML::Embperl::Req" Objekt sein. Dieses wird als erster Parameter in @_ an jede Seite übergeben. Da die meisten Web Server mehr als ein Dokument verwalten, ist es nötig, die Dokumente gegeneinander zu schützen. Embperl benutzt dazu Perl Namensräume (Packages). Standardmäßig führt Embperl jedes Dokument in seinem eigenen Namensraum aus. Das verhindert, das globale Variablen, sich gegenseitig überschreiben oder beeinflussen. Mittels der Konfigurationsanweisung EMBPERL_PACKAGE ist es möglich einen expliziten Packagenamen für ein oder mehere Dokumente vorzugeben. Dies alles verhindert aber nicht, das durch die Angabe eines Variablennamen incl. Packagenamen eine Embperlseite auf andere Namensräume zugreifen kann. Manchmal, z.B. wenn mehrere Personnen Zugriff auf die Webserverinhalte haben sollen, ist es notwendig Dokumente tatsächlich gegenseitig zuschützen. Für solche Fällen kann Embperl Safe.pm nutzen um sichere Namensräume bereit zu stellen. Ein Dokument, das in einem solchen sicheren Namensraum abläuft, kann dann nicht mehr auf andere Namensräume zugreifen. (Für weitere Informationen zu sicheren Namensräumen lesen Sie bitte die Dokumentation zu Safe.pm) Um ein Dokument in einem sicheren Namensraum ablaufen zu lassen, müssen Sie lediglich die Option optSafeNamespace setzen. Der Packagename wird dabei weiterhin automatisch von Embperl erzeugt oder kann mittels EMBPERL_PACKAGE gesetzt werden. HINWEIS: Für das ausgeführte Dokument erscheint es so, als würde der Code im Package main ausgeführt! Eine weitere Möglichkeit, um Embperl Seiten sicher zu machen, ist die Benutzung von Opcode Restriktionen. Dazu ist es nötig, zuerst ein Safe Compartment zu erstellen: B<$cp = HTML::Embperl::AddCompartment($name);> Dies erstellt ein neues Compartment mit einer Default Opcode Maske und dem Namen $name (Der Name wird später verwendet, damit Embperl weiss, welches Compartment es benutzen soll). Nun können Sie die Opcode Maske ändern. Zum Beispiel: B<$cp->deny(':base_loop');> In Ihrer Konfiguration müssen Sie die Option optOpcodeMask in EMBPERL_OPTIONS setzen und spezifizieren aus welchem Compartment die Opcode Maske (durch setzen von EMBPERL_COMPARTMENT) genommen werden soll. Beispiel (beim Gebrauch mit mod_perl): B<srm.conf:> PerlScript startup.pl SetEnv EMBPERL_DEBUG 2285 Alias /embperl /path/to/embperl/eg <Location /embperl/x> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI PerlSetEnv EMBPERL_OPTIONS 12 PerlSetEnv EMBPERL_COMPARTMENT test </Location> B<startup.pl:> $cp = HTML::Embperl::AddCompartment('test'); $cp->deny(':base_loop'); Beim Starten des Server wird dadurch die Datei startup.pl ausgeführt. startup.pl erstellt einen Compartment mit Namen 'test', in dem Schleifen gesperrt sind. Alle Seiten die unter "/embperl/x" liegen, werden nun in einem sicheren Namensraum, mit gesperrten Schleifen, ausgeführt. Hinweis: Das Package Name des Compartments wird nicht genutzt! Mehr Information zum Setzen der Opcode Mask finden Sie in der Dokumentation von Safe.pm und Opcode.pm.

AddCompartment($Name)
Fügt ein Compartment zum Gebrauch mit Embperl hinzu. Embperl nutzt nur die Opcode Maske und nicht den Packagenamen des Compartements. "AddCompartment" gibt den neu erstellten Compartment zurück, so daß die Methoden zum Freigeben oder Sperren bestimmter Opcodes aufgerufen werden können. (siehe auch "(Sichere-)Namesräume und Opcode Restriktionen") Beispiel: $cp = HTML::Embperl::AddCompartment('TEST'); $cp->deny(':base_loop');

MailFormTo($MailTo, $Subject, $ReturnField)
Sendet den Inhalt des Hashs %fdat, in der durch @ffld angegebenen Reihenfolge, zur, durch $MailTo angegeben, E-Mail Adresse, mit $Subject als Betreff. Ist $ReturnField angegeben, wird die in diesem Feld enthaltene E-Mail Adresse als "Return-Path" in der Mail angegeben. $ReturnField sollte normalerweise das Feld angeben in das der Benutzer seine E-Mail Adresse einträgt. Wenn Sie nachfolgenden Beispielcode als "Action" in Ihrem Formular angeben: <FORM ACTION="x/feedback.htm" METHOD="POST" ENCTYPE="application/x-www-form-urlencoded"> wird der Inhalt des Formulars zur angegebenen E-mail Adresse versandt. "EMBPERL_MAILHOST" gibt den SMTP Server an den "MailFormTo" benutzt. Default ist localhost. Beispiel: <HTML> <HEAD> <TITLE>Feedback</TITLE> </HEAD> <BODY> [- MailFormTo('webmaster@domain.xy', 'Mail von WWW Formular', 'email') -] Ihre Daten wurden erfolgreich versandt! </BODY> </HTML> Das Beispiel sendet eine Mail mit allen Feldinhalten des Formulars (das Formular muß als Action die URL des obigen Beispiels angeben) zu der Mailadresse 'webmaster@domain.xy'. Als Betreff wird 'Mail von WWW Formular' verwendet und der Return-Path wird auf die Adresse gesetzt, welche im Feld 'email' eingegeben wurde. HINWEIS: Sie müssen Net::SMTP (aus dem libnet Package) installiert haben, wenn Sie diese Funktion nutzen wollen.

exit
"exit" überschreibt die standard Perl "exit" Funktion. "exit" beendet die Ausführung des Dokuments und sendet alle bis dahin ausgeführten Ausgaben zum Browser. Hinweis 1: exit beendet nur die aktuelle Datei. Wurde die Datei von einer anderen mittels Execute aufgerufen, wird die aufrufende Datei fortgesetzt. Hinweis 2: Innerhalb eines Perlmoduls, das von einer Embperl Seite aus aufgerufenen wird, sollten sie "Apache::exit" verwenden, da das normale Perl "exit" ansonsten den kompletten Childprozeß beendet. "Apache::exit" führt dazu, dass die Ausführung des Moduls, wie auch der Embperl Seite, abgebrochen wird, jedoch alle Ausgaben noch zum Browser gelangen.

ProxyInput ($r, $in, $mtime, $src, $dest)
Konfiguration in srm.conf: <Location /embperl/ifunc> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI PerlSetEnv EMBPERL_INPUT_FUNC "ProxyInput, /embperl/ifunc, http://otherhost/otherpath" </Location> "ProxyInput" dient dazu den Quellentext von Embperl Dokumenten, von einer anderen URL anzufordern, statt sie direkt von der Platte zu lesen. Im obigen Beispiel würde eine Anfrage für "/embperl/ifunc/foo.html" z.B. die URL "http://otherhost/otherpath/foo.html" als Quelle für die Bearbeitung durch Embperl verwenden. Eine mögliche Anwendung ist, die Ausgabe von mod_include durch Embperl weiter bearbeiten zu lassen. Beispielkonfiguration in srm.conf für SSI und Embperl: <Location /embperl> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI PerlSetEnv EMBPERL_INPUT_FUNC "ProxyInput, /embperl, http://localhost/src" </Location> <Location /src> SetHandler server-parsed Options +Includes </Location> Die Quellen müssen unter "/src" abgelegt sein. Die eigentliche HTTP Anfrage wird jedoch an "/embperl" gerichtet. Eine Anfrage an "/embperl/foo.html" erzeugt z.B. eine Proxy-Anfrage an "/src/foo.html", welche von mod_include ausgeführt wird. Die resultierende Seite wird dann von Embperl weiterverarbeitet. Es ist ebenfalls möglich zwei unterschiedliche Ports für mod_include und Embperl zu benutzen, dadurch bleiben die URIs gleich.

LogOutput ($r, $out, $basepath)
Beispielkonfiguration in srm.conf: <Location /embperl/ofunc> SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI PerlSetEnv EMBPERL_OUTPUT_FUNC "LogOutput, /usr/msrc/embperl/test/tmp/log.out" </Location> "LogOutput" ist eine Ausgabefunktion. Sie sendet die Ausgaben zum Browser und schreibt sie in einer eindeutige Datei, die den Namen "$basepath.$$.$LogOutputFileno" bekommt, wobei $LogOutputFileno jedesmal um eins erhöht wird. Wenn Embperl auf einen Block mit Perl Code trifft ([+/-/!/$ .... $/!/-/+]) führt es folgende Bearbeitungsschritte aus: Die Schritte 1-4 werden nur beim ersten Mal, wenn Embperl auf den Perl Code trifft, ausgeführt. Wird die Seite das zweite mal abgerufen, bzw. liegt der Block in einer Schleife, muß Embperl lediglich die vorkompilierte Funktion aufrufen. Schritte 6 und 7 werden nur bei Ausgaben, d.h. "[+ ... +]" Blöcken, ausgeführt.

Was bedeutet das im Detail?
Als Beispiel nehmen wir folgenden Code: [+ <BR> $a = "Dies '&gt;' ist ein Größerzeichen" <BR> +]

1. Entfernen der HTML Tags. Danach sieht es folgendermaßen aus:
[+ $a = "Dies '&gt;' ist ein Größerzeichen" +] Die <BR>'s in diesem Fall machen keinen Sinn, sie kommen höchstwahrscheinlich von einem WYSIWYG HTML Editor, dadurch das der Benutzer zur besseren Übersicht hier eine neue Zeile beginnen wollte. Solche Editoren fügen u.U. auch ungewollte Tags wie "<FONT"> o.ä. in den Perl Code ein. Durch das entfernen solcher Tags, stellt Embperl sicher, dass Designer, die mit solchen Editoren arbeiten, den Perl Code dadurch nicht zerstören können. Es gibt auch Fälle, wo HTML Tags wirklich gebraucht werden. Zum Beispiel: Nehmen wir an, Sie wollen folgendes Ausgeben: [+ "<FONT COLOR=$col>" +] Ohne weitere Maßnahmen, würde Embperl folgendes daraus machen: [+ "" +] Um aber dennoch HTML Tags zu verwenden gibt es verschiedene Möglichkeiten: Schreiben Sie nur den wirklich notwendigen Teil innerhalb des "[+ ... +]" Blocks und verlagern sie das HTML Tag nach außerhalb. Dies ist der unproblematischste Weg und sollte wenn immer möglich gewählt werden. Durch Voranstellen eines Backslashs ('\'). Sie können HTML kodierte Zeichen benutzen. Die meisten HTML Editoren machen dies automatisch. (In diesem Fall brauchen Sie sich nicht weiter darum zu kümmern.) Dies verhindert grundsätzlich das Entfernen von HTML Tags. HINWEIS: In den Fällen b-d sollten Sie ebenfalls die Ausgabe-HTML-Kodierung beachten (siehe unten). Zu beachten ist ebenfalls, daß Embperl den Perl Dateihandle Operator (<>) als HTML Tag interpretiert und ihn damit entfernt. Anstelle von [- $line = <STDIN>; -] sollten Sie eine der folgenden Schreibweise verwenden: Benutzen Sie einen High-Level HTML Editor, wird er wahrscheinlich Version (b) automatisch erzeugen.

2. Transformieren HTML/URL kodierter Zeichen in entsprechende ASCII Zeichen.
Da Perl HTML kodierte Zeichen, wie "$a &lt; $b", nicht versteht, übersetzt Embperl dies zu "$a < $b". Nehmen wir das Beispiel von vorhin, dann sieht es jetzt so aus: [+ $a = "Dies '>' ist ein Größerzeichen" +] Dies dient wiederum der Unterstützung von High-Level Editoren. Dadurch ist es unerheblich, wenn Ihr Editor "&gt;" statt > im Quellentext schreibt. Auch hier ist es manchmal nötig, die HTML kodierten Zeichen zu erhalten. Dazu bietet Embperl folgende Möglichkeiten: Durch Voranstellen eines Backslashs ('\'). Schreiben Sie das erste '&' als HTML kodiertes Zeichen (&amp;). Ein HTML Editor wird dies von sich machen, wenn Sie "&gt;" als Text eingeben. Dies verhindert grundsätzlich das Dekodieren von HTML kodierten Zeichen. Da nicht jeder einen High Level oder WYSIWYG HTML Editor benutzt, gibt es eine Option, um Schritt 1 und 2 vollständig zu sperren. Durch setzen von optRawInput in EMBPERL_OPTIONS läßt Embperl den Perl Code unberührt. Diese Option sollten Sie setzen, wenn Sie einen ASCII Editor benutzen, bei Benutzung eines HTML Editors, sollte diese Option nicht nötig sein. Sie können optRawInput auch innerhalb Ihres Dokument ein-/ausschalten, indem Sie $optRawInput 1 oder 0 zuweisen, wobei zu beachten ist, daß die Änderung erst ab dem nächsten Block wirksam wird. Beispiel: [- $optRawInput = 1 -] [- $line = <FILEHANDLE> -]

3. Entfernen Sie aller Carriage Returns
Embperl entfernt vor dem Übersetzen alle Carriage Returns (\r), um sicherzustellen, daß Programme die unter DOS/Windows erstellt wurden, auch unter Perl 5.004 und Unix laufen.

4. Übersetzen des Perl Codes als eigenständige Funktion.
Der nächste Schritt generiert eine Funktion aus Ihrem Perl Code. Das obige Beispiel sieht danach wie folgt aus: sub foo { $a = "Dies '>' ist ein Größerzeichen" } Die Funktion wird vom Perlinterpreter in einem internen vorkompilierten Format gespeichert und kann somit später immer wieder aufgerufen werden, ohne die Schritte 1-4 wiederholen zu müssen. Embperl erkennt, wenn das gleiche Dokument ein zweites mal angefordert wird und ruft lediglich die bereits kompilierte Funktion auf. Dadurch wird auch die Ausführung von dynamischen Tabellen und Schleifen beschleunigt, da der Perl Code nur bei der ersten Iteration kompiliert werden muss.

5. Aufrufen der Funktion
Nun kann die Funktion aufgerufen werden, um den Code tatsächlich auszuführen. Falls nicht ein "[+ ... +]" Block ausgeführt wird, ist die Bearbeitung damit abgeschlossen.

6. URL/HTML kodieren von entsprechenden Sonderzeichen im Rückgabewert.
Unser Beispiel erzeugt die Zeichenkette: "Dies '>' ist ein Größerzeichen" Das Größerzeichen hier ist normaler Text (und nicht das Ende eines HTML Tags), gemäss HTML Spezifikation muss es als "&gt;" zum Browser gesendet werden. In vielen Fällen entsteht kein Problem, wenn man direkt das Größerzeichen sendet, da der Browser höchstwahrscheinlich das '>' als normalen Text ausgeben wird. In diesem Fall wäre es auch möglich gleich "&gt;" in unseren Perl Code schreiben, wenn jedoch die Zeichenkette z.B. Ergebnis einer Datenbankabfrage ist und/oder nationale Sonderzeichen enthält, ist es notwendig eine HTML Kodierung der Zeichen durchzuführen. Weiterhin werden Tags, die URLs enthalten (wie "<A"> oder "<FRAME">), insofern speziell behandelt, als dass Ausgaben innerhalb des Parameters der die URL enthält, URL kodiert werden. (z.B. wird '&' zu %26 und Leerzeichen zu '+'). Dies ist nötig, damit der Browser Sonderzeichen korrekt interpretiert. Beispiel: <A HREF="http://host/script?name=[+$n+]"> Falls $n den Wert "Mein Name" enthält, wird die resultierende URL: http://host/script?name=Mein+Name In einigen Fällen ist es nützlich, die Ausgabekodierung abzuschalten. Dies kann mit der Variablen $escmode geschehen. Beispiel: (Um das Beispiel einfacher lesbar zu machen, setzen wir voraus, daß "optRawInput" gesetzt ist. Andernfalls sind die in 1 - 3 beschriebenen Punkte zu beachten) [+ "<FONT COLOR=5>" +] Dies würde zum Browser als "&lt;FONT COLOR=5&gt;" gesandt, was dazu führt das der Tag exakt so auf dem Bildschirm zusehen ist, statt das sich die Farbe des folgenden Textes ändert. [+ local $escmode=0 ; "<FONT COLOR=5>" +] Dies schalten die HTML Kodierung (lokal) ab und das Tag wird exakt so wie Sie es geschrieben haben zum Browser geschickt. HINWEIS: $escmode kann nur einmal innerhalb eines "[+ ... +]" Blocks gesetzt werden. Der erste Wert der $escmode zugewiesen wird, gilt für alle Ausgaben, innerhalb des Blocks. Möchten Sie $escmode hin- und herschalten, müssen Sie mehrere "[+ ... +]" Blöcke verwenden.

7. Senden des Rückgabewertes (an Browser oder Datei etc.)
An diesem Punkt ist die Ausgabe fertig aufbereitet und kann zum Browser gesandt werden. Falls Sie nicht die Option "optEarlyHttpHeader" gesetzt haben, werden alle Ausgaben bis zur vollständigen Ausführung des Dokuments zwischengespeichert. Ist das ganze Dokument abgearbeitet, werden zuerst alle HTTP Header gesendet (dies erlaubt während der Erstellung des Dokuments zusätzliche HTTP Header hinzuzufügen) und anschließend der eigentliche Inhalt. Tritt während der Verarbeitung ein Fehler auf, wird statt dem Inhalt eine Fehlerseite zum Browser gesandt. Um die beste Performance von Embperl zu erzielen, ist es notwendig, das Logging auf ein Minimum zu beschränken. Sie können Embperl drastisch verlangsamen, wenn Sie alle Logging Option einschalten. Vorallem sollten Sie niemals dbgFlushOutput oder dbgFlushLog auf einen Produktionsserver einschalten. Während der geringfügige Performanceverlust beim Debuggen nicht auffällt, kann er auf einem stark belasteten Server durchaus ins Gewicht fallen. Auch die Optionen optDisableChdir, optDisableHtmlScan, optDisableCleanup haben Auswirkungen auf die Performance. Lesen Sie ebenfalls mod_perl_tuning.pod für weitere Ideenen zur Performancesteigerung. Fehler sind keine bekannt. Es wird jedoch empfohlen mindestens Perl 5.004_04 und mod_perl 1.08 einzusetzen, da ältere Versionen Speicherlecks aufweisen. Embperl wurde erfolgreich getestet

unter Linux 2.x mit
Rückmeldungen bestätigen, dass es ebenfalls auf fast allen anderen Unix Varianten problemlos läuft.

unter Windows NT 4.0 mit

unter Windows 95/98 mit

Rückmeldungen/Anregungen/Probleme/Fehlerreports
Diskussionen zu allen Fragen/Problemen rund um Embperl werden auf der Embperl Mailingliste (embperl@perl.apache.org) geführt. Sollten Sie Probleme mit Embperl haben, die sich nach der Lektüre dieser Dokumentation sowie der FAQs nicht lösen lassen, ist die Mailingliste der richtige Ort um nachzufragen. Oft wurden Probleme schon diskutiert, deshalb lohnt sich ein Blick in die Archive der Liste. http://www.ecos.de/~mailarc/embperl/ oder in das Archiv der mod_perl Mailingliste für Fragen in Zusammenhang mit mod_perl http://forum.swarthmore.edu/epigone/modperl Um die Mailingliste zu abbonieren, senden Sie eine Mail an embperl-subscribe@perl.apache.org, zum von der Liste gestrichen zu werden genügt eine Mail an embperl-unsubscribe@perl.apache.org . Haben Sie eine Website die Embperl benutzt, würde ich mich über eine Rückmeldung freuen und diese ggf. in die Liste der Sites die Embperl nutzen ( http://perl.apache.org/embperl/Sites.pod.1.html ) aufnehmen.

Kommerzieller Support
ecos bietet die Möglichkeit, Support für Embperl zu kaufen. Dies umfasst: Sie erreichen uns via http://www.ecos.de oder info@ecos.de Für weiter Informationen zu unserem Supportangebot, siehe http://www.ecos.de/x/index.htm/support/r_support.htm

Wie kann ich die Entwicklung von Embperl unterstützen
Wenn Sie Embperl einsetzen und dessen weitere Entwicklung unterstützen möchten, gibt es zwei Möglichkeiten: Sie implementieren ihr Wunschfeature selbst und senden uns einen Patch. Sie kaufen kommerziellen Support (siehe oben). Auch wenn sie vielleicht die selben Antworten auf ihre Fragen auf der Mailingliste bekommen würden, macht es Sinn Support zu kaufen. Zum einen können sie sich dann sicher sein, immer eine Antwort auf ihre Fragen zu bekommen, zum anderen unterstützen sie damit die weitere Entwicklung von Embperl und ermöglichen uns mehr Zeit und Resourcen dafür aufzubringen.

Informationen
mod_perl http://perl.apache.org/ mod_perl FAQ http://perl.apache.org/faq Embperl http://perl.apache.org/embperl/ Embperl (deutsch) http://www.ecos.de/embperl/ DBIx::Recordset ftp://ftp.dev.ecos.de/pub/perl/dbi Apache Webserver http://www.apache.org/ ben-ssl (freier httpsd) http://www.apache-ssl.org/ mod_ssl (freier httpsd) http://www.modssl.org/ stronghold (kommerizieller httpsd) http://www.c2.net/ Europa http://www.eu.c2.net/ weitere Apache module http://perl.apache.org/src/apache-modlist.html

Download
mod_perl http://www.perl.com/CPAN/modules/by-module/Apache Embperl ftp://ftp.dev.ecos.de/pub/perl/embperl DBIx::Recordset ftp://ftp.dev.ecos.de/pub/perl/dbi Win NT/95/98 Binaries Apache/perl/ mod_perl/Embperl ftp://theoryx5.uwinnipeg.ca/pub/other/ europe http://www.robert.cz/misc/ RPM source ftp://ftp.akopia.com/pub/support/srpm/ binary redhat 6.0 ftp://ftp.akopia.com/pub/support/6.0/ binary redhat 6.1 ftp://ftp.akopia.com/pub/support/6.1/ Debian packages http://www.cse.unsw.edu.au/~gusl/embperl PPM für ActiveState http://theoryx5.uwinnipeg.ca/ppmpackages/

CVS
Die aktuelle Entwicklerversion ist via CVS verfügbar. Weitere Informationen dazu stehen in "perldoc CVS.pod".

Emacs
Von: Erik Arneson [erik@mind.net] Man braucht mmm.el von http://members.tripod.com/gchen2/xemacs/ Anschließend muß man mein mmm-embperl.el downloaden von http://www.aarg.net/erik/mmm-embperl.el Dokumentation ist in den Dateien enthalten.

VIM
Vim Syntaxfile von Steve Willer: http://www.interlog.com/~willer/embperl.vim Vim Syntaxfile von Kee Hinckley: http://www.somewhere.com/software/

Dreamweaver
Dreamweaverextention welche Dreamweaver veranlasst den Embperl code in Ruhe zu lassen befindet sich unter http://www.somewhere.com/software/ G. Richter (richter@dev.ecos.de)