EmbperlD(3)

NAME
HTML::Embperl - einbetten von Perlcode in HTML Dokumente

SYNOPSIS
Embperl ist ein Perlmodul welches es erlaubt beliebigen Perlcode in HTML Dokumente einzufuegen.

DESCRIPTION

Aufrufen/Konfigurieren von Embperl

  mod_perl Konfiguration
Um HTML::Embperl als content handler unter mod_perl laufen zu lassen, sind folgende Zeilen in der Apache Konfigurationsdatei httpd.conf noetig:

Beipiel fuer 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 fuer 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 Moeglichkeit ist, alle Dateien mit einer bestimmten Endung von Embperl bearbeiten zu lassen. Eine Konfiguration dafuer wuerde 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" uebersetzt 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 ausgefuehrt werden. Weiterhin koennen andere Perlprogramme oder -module es direkt aufrufen.

Der Aufruf von der Befehlszeile sieht folgendermassen 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]"

htmlfile
    Datei welche von Embperl bearbeitet werden soll.

query_string
    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.

-o outputfile
    Optional. Gibt den Dateinamen an, in den das Ergebnis geschrieben wird. Default ist die Standardausgabe.

-l logfile
    Optional. Name der Logdatei. Default ist "/tmp/embperl.log".

-d debugflags
    Optional. Gibt an, welche Debuginformationen in die Logdatei geschrieben werden. (siehe "EMBPERL_DEBUG" fuer moegliche Werte)

Um Embperl als CGI Skript zu nutzen, muessen 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" uebergeben 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 Sicherheitsgruenden 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 beschraenken.

  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 moeglich andere Dokumente (z.B. Kopf- oder Fusszeilen) in Embperlseiten einzufuegen.

Die Kurzform muessen lediglich Dateinamen und ggf. Parameter fuer 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 fuer die Langform sind:

inputfile
    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, dass die Quelle die selbe ist und verwendet den selben Packagenamen, sowie compiliert die Perlteile nur wenn "mtime" sich aendert oder undefiniert ist.

sub Ruft die durch diesen Parameter angegebene Funktion auf (siehe auch [$ "sub" $]). Momentan muss die Funktion entweder in der selben Embperldatei definiert sein oder die Embperldatei muss vorher importiert worden sein.

input
    Referenz auf einen Skalar, welcher den Quellentext enthaelt. inputfile sollte ebenso angegeben werden, um die Quelle zu benennen. Der Name kann dabei beliebiger Text sein.

mtime
    Zeitpunkt der letzten Aenderung des Quellentextes. Der Quellentext wird nur dann neu uebersetzt, wenn sich mtime aendert oder wenn mtime "undef" ist.

outputfile
    Datei, in die die Ausgabe geschrieben wird. Ist keine Datei angegeben, wird die Standardausgabe benutzt.

output
    Referenz auf einen Skalar, in welchen die Ausgabe geschrieben werden soll.

import
    Ein Wert von Null veranlasst Embperl die Seite nicht auszufuehren, sondern alle darin enthaltenen Funktionen zu definieren. Dies ist noetig, um sie mittels des sub Parameters der Execute Funktion aufrufen zu koennen oder als Vorbereitung fuer einen spaeteren Import.

    Ein Wert von Eins veranlasst Embperl die Seite nicht auszufuehren, sondern alle darin enthaltenen Funktionen zu definieren und diese in das aktuelle Package zu importieren.

    Siehe auch "[$ sub $]" Metacommand.

cleanup
    Dieser Wert gibt an, ob and wann das "Cleanup" des Packages ausgefuehrt werden soll. (Siehe auch "Variablen Gueltigkeitsbereich und Cleanup")

    cleanup = -1
        Es wird kein Cleanup ausgefuehrt.

    cleanup = 0 oder nicht spezifiziert
        Unter mod_perl wird das Cleanup erst ausgefuehrt, nachdem die Verbindung zum Client beendet wurde, auch wenn "Execute" mehrfach waehrend eines Request aufgerufen wird.

        In allen anderen Faellen wird das Cleanup sofort ausgefuehrt.

    cleanup = 1
        Cleanup wird sofort ausgefuehrt.

param
    Eine Referenz auf ein Array, um dem aufgerufenen Dokument Parameter zu uebergeben.

     Beispiel:

        HTML::Embperl::Execute(..., param => [1, 2, 3]) ;
        HTML::Embperl::Execute(..., param => \@parameters) ;

    Ueber das Array @param kann die aufgerufene Seite auf die Parameter zugreifen. Siehe eg/x/Excute.pl aus der Embperl Distribution fuer ein detailliertes Beispiel.

ffld and fdat
    Kann benutzt werden, um die beiden Embperlvariablen @ffld und %fdat zu setzen.

firstline
    Gibt die erste Zeilennummer der Quellendatei an (Default: 1)

options
    Wie "EMBPERL_OPTIONS" (siehe unten), ausser fuer 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 fuehrt, das der Request haengt.

debug
    Wie "EMBPERL_DEBUG" (siehe unten).

escmode
    Wie "EMBPERL_ESCMODE" (siehe unten).

package
    Wie "EMBPERL_PACKAGE" (siehe unten).

virtlog
    Wie "EMBPERL_VIRTLOG" (siehe unten). Wenn virtlog gleich uri ist, wird die Embperl Logdatei gesendet.

uri Die URI des Request. Wird nur fuer Virtlog Feature benoetigt.

compartment
    Wie "EMBPERL_COMPARTMENT" (siehe unten).

input_func
    Wie "EMBPERL_INPUT_FUNC" (siehe unten). Zusaetzlich ist es moeglich eine Codereferenz anzugeben, die entsprechende Funktion wird dann als Eingabefunktion aufgerufen. Ebenso ist die Angabe einer Arrayreferenz moeglich, wobei das erste Element dann die Codereferenz enthaelt und alle weiteren Elemente als Parameter der Funktion uebergeben werden.

output_func
    Wie "EMBPERL_OUTPUT_FUNC" (siehe unten). Zusaetzlich ist es moeglich eine Codereferenz anzugeben, die entsprechende Funktion wird dann als Ausgabefunktion aufgerufen. Ebenso ist die Angabe einer Arrayreferenz moeglich, wobei das erste Element dann die Codereferenz enthaelt und alle weiteren Elemente als Parameter der Funktion uebergeben werden.

cookie_name
    Wie "EMBPERL_COOKIE_NAME" (siehe unten).

cookie_path
    Wie "EMBPERL_COOKIE_PATH" (siehe unten).

cookie_domain
    Wie "EMBPERL_COOKIE_DOMAIN" (siehe unten).

cookie_expires
    Wie "EMBPERL_COOKIE_EXPIRES" (siehe unten).

errors
    Erwartet eine Referenz auf ein Array. Nach der Rueckkehr der Funktion enthaelt das Array alle Fehlermeldungen der aufgerufenen Seite, soweit welche aufgetreten sind.

  Hilfsfunktionen fuer Execute

HTML::Embperl::Init ($Logfile, $DebugDefault)
    Diese Funktion dient dazu, die Logdatei sowie die Debugflags, die fuer die folgenden Aufrufe von "Execute" genutzt werden, zu setzen. Es kann immer nur eine Logdatei existieren, der Pfad kann jedoch jederzeit geaendert werden.

HTML::Embperl::ScanEnvironement (\%params)
    Durchsucht alle Umgebungsvariablen (%ENV) und setzt %params fuer die Benutzung von "Execute". Alle Embperl Konfigurationsvariablen, ausser EMBPERL_LOG, werden erkannt.

  Beispiele fuer 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 aendern wenn $src sich aendert

 $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 ;

 # Einfuegen eines gemeinsammen Kopfes in eine Embperlseite
 # der sich in /pfad/zu/kopf.html befindet

 [- Execute ('/pfad/zu/kopf.html') -]

Runtime Konfiguration
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" gegenueber "SetEnv" ist, dass unterschiedliche Werte fuer 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 nuetztlich, 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 nuetzlich, um die Serversicherheit zu erhoehen.

  EMBPERL_COMPARTMENT
Gibt dem Namen des Compartments fuer die Opcodemaske an. (Siehe "(Sichere-)Namensraeume und Opcode Restriktionen" fuer Details.)

  EMBPERL_ESCMODE
Gibt den Anfangswert fuer "$escmode" an (siehe unten).

  EMBPERL_LOG
Pfad fuer die Embperl Logdatei. Diese enthaelt Informationen darueber, wie Embperl den eingebetteten Perlcode ausfuehrt. Wieviele Informationen geschrieben werden haengt von der Einstellung der Debugflags ab (siehe "EMBPERL_DEBUG"). Default ist /tmp/embperl.log.

HINWEIS: Unter mod_perl muss "EMBPERL_LOG" mittels "PerlSetEnv" gesetzt werden, damit es schon bei Serverstart wahrgenommen wird.

  EMBPERL_PACKAGE
Name des Packages in dem der Code ausgefuehrt wird. Wenn kein Package angegeben ist, erzeugt Embperl fuer 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" fuer ein Beispiel, wie dies in Webserverkonfiguration eingestellt werden kann.

  EMBPERL_OPTIONS
Diese Bitmaske gibt diverse Optionen fuer die Ausfuehrung von Embperl an. Damit koennen bestimmte Features von Embperl gesperrt oder freigegeben sowie das Verhalten von Embperl beeinfluss werden. Um mehrere Optionen anzugeben sind die Werte zu addieren.

optDisableVarCleanup = 1
    Cleanup wird nicht nach jedem Request ausgefuehrt.

optDisableEmbperlErrorPage = 2
    Fuehrt dazu, dass Embperl im Fehlerfall nicht seine eigene Fehlerseite anzeigt, sondern so viel wie moeglich 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.

optReturnError = 262144
    Wenn diese Option gesetzt ist, sendet Embperl keine Fehlerseite, sondern liefert den Fehlercode an Apache oder das aufrufende Programm zurueck. Unter Apache ermoeglicht dies die "ErrorDocument" Anweisung zu benutzen, um eine eigene Fehlerseite anzuzeigen.

optSafeNamespace = 4
    Veranlasst Embperl den Code in einem sicheren Namensraum auszufuehren. Dadurch ist es nicht mehr moeglich auf Daten ausserhalb des Packages zuzugreifen. (Siehe "(Sichere-)Namensraeume und Opcode Restriktionen" fuer Details.)

optOpcodeMask = 8
    Veranlasst Embperl eine Operator Maske anzuwenden. Dadurch ist es moeglich, bestimmte, unsichere, Opcodes zu sperren. (Siehe "(Sichere-)Namensraeume und Opcode Restriktionen" fuer Details.)

optRawInput = 16
    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 unerwuenschte HTML Tags in den Perlcode einfuegt 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 zurueck, wie Sie ihn im Editor eingegeben haben.

optEarlyHttpHeader = 64
    Normalerweise werden die HTTP Header von Embperl gesendet, nachdem der Request bearbeitet wurde. Dies ermoeglicht, waehrend der Bearbeitung des Dokuments beliebige Header zu setzen und Embperl kann den "Content-Length" Header berechnen. Ausserdem 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 fuehrt dazu, das die Header sofort, vor der Ausfuehrung des Dokuments, gesendet werden und die Ausgabe nicht gepuffert ist.

optDisableChdir = 128
    Ohne diese Option setzt Embperl das aktuelle Verzeichnis entsprechend dem Verzeichnis, in dem das ausgefuehrte Skript steht. Dies ermoeglicht 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.

optDisableFormData = 256
    Diese Option verhindert das Setzen von %fdat und @ffld. Embperl ignoriert die gesendeten Formulardaten vollstaendig.

optDisableHtmlScan = 512
    Wenn gesetzt, verhindet diese Option das Bearbeiten aller HTML Tags vollstaendig. Embperl sucht dann nur noch nach <[+/-/!/$ ... $/!/-/+]> Bloecken. Dies schaltet dynamische Tabellen, Formularbearbeitung usw. ab.

optDisableInputScan = 1024
    Verhindert die Bearbeitung aller Eingabe Tags. (<INPUT><TEXTAREA><OPTION>)

optDisableTableScan = 2048
    Verhindert die Bearbeitung aller Tabellen Tags. (<TABLE><TH><TR><TD><MENU><OL><SELECT><UL>)

optDisableMetaScan = 4096
    Verhindert die Bearbeitung aller Meta Tags. (<META HTTP-EQUIV>)

optAllFormData = 8192
    Diese Option veranlasst Embperl all Formularfelder in %fdat und @ffld einzufuegen, auch wenn sie leer sind. Leere Formularfelder werden als leere Zeichenkette eingefuegt. Ohne diese Option werden leere Formularfelder nicht zu %fdat und @ffld hinzufuegt.

optRedirectStdout = 16384
    Leitet die Standardausgabe vor jedem Request auf dem Embperlausgabestrom um und setzt sie anschliessend zurueck. 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 moeglich.

optUndefToEmptyValue = 32768
    Normalerweise, wenn Embperl fuer ein Eingabefeld keinen Wert in %fdat findet, laesst es das HTML Tag unveraendert. Mit dieser Option behandelt Embperl das Feld so, als waere eine leere Zeichenkette in %fdat fuer dieses Feld, d.h. wenn kein "VALUE" Attribut vorhanden ist fuegt Embperl ein "VALUE=""" ein.

optNoHiddenEmptyValue = 65536 (ab 1.2b2)
    Mit dieser Option erzeugt Embperl beim Hidden Metacommand keine Hidden-Felder fuer leere Zeichenketten.

optAllowZeroFilesize = 131072 (ab 1.2b2)
    Dokumente der Dateilaenge Null fuehren normalerweise zu einem Fehler "NOT_FOUND (404)". Mit dieser Option liefert Embperl ein leeres Dokument zurueck.

optKeepSrcInMemory =  524288  (ab 1.2b5)
    Veranlasst Embperl den Quellencode des Dokuments im Speicher zuhalten. (Der compilierte Perlcode wird immer im Speicher gehalten, unabhaenig von diesem Flag).

optKeepSpaces = 1048576 (ab 1.2b5) 	       = 0x100000,
    Verhindert das Entfernen von Leerzeilen und Zwischenraeumen. Dies ist sinnvoll fuer Nicht-HTML-Dokumente.

optOpenLogEarly =  2097152 (ab 1.2b5)
    Diese Option veranlasst Embperl die Logdatei zu oeffnen, 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 oeffnen.

optUncloseWarn =   4194304 (ab 1.2b6)
    Verhindert das Embperl eine Warnung ueber 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.

dbgStd = 1
    Minimale Informationen.

dbgMem = 2
    Speicherverwaltung.

dbgEval = 4
    Zeigt den Code und das Resultat beim Ausfuehren von Perl.

dbgCmd = 8
    Schreibt alle Metacommands und HTML Tags, die ausgefuehrt werden, in die Logdatei.

dbgEnv = 16,
    Listet alle Umgebungsvariablen.

dbgForm = 32
    Listet die an das Dokument gesandten Formulardaten.

dbgTab = 64
    Zeigt die Bearbeitung von dynamischen Tabellen.

dbgInput = 128
    Zeigt die Bearbeitung von Eingabefeldern.

dbgFlushOutput = 256
    Fuehrt ein "flush" nach jeder Ausgabe aus. Dies dient lediglich zum Debuggen von Abstuerzen und fuehrt normalerweise zu einer deutlichen Verlangsamung der Ausgabe.

dbgFlushLog = 512
    Fuehrt ein "flush" nach jedem Schreiben in die Logdatei aus. Dies dient lediglich zum Debuggen von Abstuerzen und fuehrt normalerweise zu einer deutlichen Verlangsamung der Verarbeitung.

dbgAllCmds  = 1024
    Schreibt alle Metacommands und HTML Tags in die Logdatei, unabhaenig davon ob sie ausgefuehrt werden oder nicht. Ein '+' kennzeichnet dabei, dass Embperl diesen Befehl ausfuehrt.

dbgSource = 2048
    Schreibt jeweils den naechsten Teil des Quellencodes in die Logdatei, der ausgefuehrt wird. (Dadurch kann die Logdatei recht umfangreich werden)

dbgFunc = 4096
    Diese Option ist nur verfuegbar, wenn Embperl mit "-DEPDEBUGALL" uebersetzt wurde. Wenn gesetzt, werden alle Embperl internen Funktionsaufrufe in die Logdatei geschrieben. Dient dem Debuggen von Embperl selbst.

dbgLogLink = 8192
    Fuegt oben auf jeder Seite einen Link ein, der dazu benutzt werden kann, die Logdatei fuer 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>

dbgDefEval = 16384
    Erzeugt jedesmal einen Eintrag in der Logdatei, wenn neuer Perlcode uebersetzt wird.

dbgHeadersIn = 262144
    Schreibt alle HTTP Header in die Logdatei.

dbgShowCleanup = 524288
    Gibt jede Variable, sowie deren Wert, die am Ende des Request "aufgeraeumt" wird, aus.

dbgProfile = 1048576 (ab 1.2b4)
    Wenn gesetzt, wird fuer jede Quellencodezeile die Zeit, seit dem Start des Requests, ausgegeben. (dbgSource muss ebenfalls gesetzt sein)

dbgSession = 2097152 (ab 1.2b4)
    Empfangen und Senden von Session cookies wird geloggt.

dbgImport =  4194304 (ab 1.2b5)
    Zeigt, wie Funktionen in andere Packages importiert werden.

Ein guter Wert fuer den Anfang ist 2285 oder 10477. Letzteres ermoeglicht das Anzeigen der Logdatei via Browser ("EMBPERL_VIRTLOG" muss ebenfalls gesetzt sein.)

  EMBPERL_INPUT_FUNC
Diese Konfigurationsanweisung ermoeglicht, statt den Quellentext aus einer Datei zu lesen (oder ihn einem Skalar zu entnehmen), die angegebene Funktion aufzurufen, welche fuer das Bereitstellen des Quellentextes verantwortlich ist. Die Funktion muss folgendermassen aussehen:

 InputFunc ($r, $in, $mtime, weitere Parameter...) ;

$r  Apache Request Record (siehe perldoc Apache)

$in eine Referenz auf einen Skalar, in welchen der Quellentext abgelegt werden soll.

     Beispiel:

     open F, "filename" ;
     local $\ = undef ;
     $$in = <F> ;
     close F ;

$mtime
    eine Referenz auf einen Skalar, welcher den Zeitpunkt der letzten Aenderungen zurueck liefern soll.

     Beispiel:

     $$mtime = -M "filename" ;

Es koennen 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 fuer 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, fuer eine Funktion die von Embperl bereit gestellt wird.

HINWEIS: Es gibt weiterhin zwei Module (HTML::EmbperlChain und Apache::EmbperlFilter) die die Moeglichkeit bieten Embperl und andere Module zu verketten.

  EMBPERL_OUTPUT_FUNC
Diese Konfigurationsvariable erlaubt das Angeben einer Funktion, die die Ausgabe erledigt. Die Funktion muss folgende Form haben:

 OutputFunc ($r, $out, weitere Parameter...) ;

$r  Apache Request Record (siehe perldoc Apache)

$out
    Referenz auf einen Skalar, welcher die Ausgabe von Embperl enthaelt.

Es koennen 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 fuer 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, fuer eine Funktion die von Embperl bereit gestellt wird.

HINWEIS: Es gibt weiterhin zwei Module (HTML::EmbperlChain und Apache::EmbperlFilter) die die Moeglichkeit 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_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 fuer Object Store und Lock Manager von Apache::Session angegeben (siehe "Session Handling")

  EMBPERL_SESSION_ARGS
Liste von zusaetzlichen Parametern fuer Apache::Session Klassen (Leerzeichen getrennt) (siehe "Session Handling"). Beispiel:

  PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=www Password=secret"

  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. Default ist kein Ablaufzeitpunkt.

Syntax
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 anstossen.

Bevor Embperl Befehle bearbeitet (ebenso fuer 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 Aequvivalente umgewandelt, so dass sie der Perlinterpreter versteht. Dies ist noetig, 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 eingefuegt hat, an einer Stelle, wo lediglich ein Zeilenumbruch sein sollte.) Um dieses zu unterbinden, koennen 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, dass Sie die Ein- und Ausgabekodierung und -dekodierung, die Embperl durchfuehrt, 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 noetig '[[' zu schreiben.

Embperl benutzt keine HTML Kommentare (z.B. <! ... !>) oder andere spezielle HTML Tags, da es mit manchen HTML Editoren nicht, oder nur sehr umstaendlich, moeglich 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 Faellen das schreiben der Dokumente erheblich.

  [+ Perl Code +]
Ersetzt den Befehl durch das Resultat der Ausfuehrung des Perl codes. "Perl Code" kann dabei beliebiger Perl code sein.

Beispiel:

 [+ $a +]        Ersetzt [+ $a +] mit dem Inhalt der Variablen $a.

 [+ $a+1 +]      Beliebige Ausdruecke koennen benutzt werden.

 [+ $x[$i] +]    Auch Arrays, Hashs oder komplexere Ausdruecke 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 -]
Fuehrt den "Perl Code" aus. In der Ausgabe wird dieser Befehl jedoch vollstaendig entfernt.

Beispiel:

 [- $a=1 -]            Setzt die Variable $a auf 1.

 [- use SomeModule -]  Andere Perlmodule koennen genutzt werden.

 [- $i=0; while ($i<5) {$i++} -]  Auch komplexer Code kann verwendet werden.

HINWEIS: Perlbefehle, wie "if", "while", "for", etc., muessen innerhalb eines Embperl Blockes abgeschlossen werden. Es ist nicht moeglich das "if" in einem Block zu schreiben und die abschliessenden Klammer ('}') in einem anderen Block. Dies ist nur mit "[* Perl Code *]" Bloecken moeglich.

HINWEIS: Um Perlfunktionen zu definieren, benutzen Sie "[! Perl Code !]" (siehe unten) da dies vermeidet, dass die Funktion bei jedem Aufruf neu uebersetzt wird.

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

  [* Perl Code *]
(ab 1.2b2)

Aehnlich wie "[- Perl Code -]". Der Hauptunterschied ist, dass "[- Perl Code -]" Bloecke immer ihren eigenen Gueltigkeitsbereich haben, waehrend "[* Perl Code *]" Bloecke im selben Gueltigkeitsbereich ablaufen. Dies ermoeglicht lokale Variablen (mit "local") mit einem Gueltigkeitsbereich, der die ganze Seite umfasst, zu definieren. Normalerweise ist es nicht noetig lokale Variablen zu definieren, da Embperl jedem Dokument einen eigenen Namensraum zuordnet und die globalen Variablen nach jedem Request wieder aufgeraeumt werden. In speziellen Faellen (z.B. um eine Embperl Seite rekursiv mittes Execute aufzurufen), ist es jedoch hilfreich.

Ein zweiter Grund ist, die Moeglichkeit Perlbefehle zu nutzen, die sich ueber mehrere Bloecke hinziehen. Perls "if", "while", "for", etc. koennen sich nicht ueber mehrere "[- Perl Code -]" Bloecke hinziehen, jedoch sehr wohl ueber mehrere "[* Perl Code *]" Bloecke.

Beispiel:

  [* foreach $i (1..10) { *]

    [- $a = $i + 5 -]
    Schleifenzaehler + 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 -]
    Schleifenzaehler + 5 = [+ $a +] <br>

  [$ endforeach $]

HINWEIS 1: "[* ... *]" Bloecke muessen immer mit ;,{ oder } enden!

HINWEIS 2: "[* ... *]" Bloecke koennen nicht innerhalb eines HTML Tags, welches von Embperl interpretiert wird, verwendet werden. (Ausser die Bearbeitung des entsprechden Tags wurde ausgeschaltet)

HINWEIS 3: Da die Ausfuehrung von "[- ... -]" Bloecken durch Embperl gesteuert wird, kann Embperl deutlich detailliertere debugging Ausgaben in der Logdatei dafuer erzeugen. Ausserdem existieren fuer "[- ... -]" keinerlei Restriktionen, wo sie genutzt werden koennen.

  [# 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: "[* ... *]" Bloecke werden vor Kommentarbloecken ausgewertet, deshalb werden sie auch innerhalb von Kommentarbloecken ausgefuehrt.

HINWEIS 2: Alles innerhalb des Komentarblocks (ausser "[* ... *]") wird aus dem Quellentext entfernt, deshalb ist es moeglich, Teile des Dokuments damit auszukommentieren.

  [$ Cmd Arg $] (Meta-Commands)
Ausfuehren eines Embperl Meta-Commands. Cmd kann einer der folgenden Befehle sein: (Arg variiert, je nach Befehl).

if, elsif, else, endif
    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 Saetze zum Browser, in Abhaenigkeit davon, ob die GET-Methode benutzt wurde, um dieses Dokument abzurufen.

while, endwhile
    Fuehrt 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 ausgefuehrt wird, ausser optRawInput ist gesetzt.

do, until
    Fuehrt eine Schleife aus, bis Arg des until Befehls wahr ist.

    Beispiel:

     [- $i = 0 -]
     [$ do $]
         [+ $i++ +] <BR>
     [$ until $i > 10 $]

foreach, endforeach
    Fuehrt eine Schleife aus, fuer 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 $]

hidden
    Arg gibt keinen, einen oder zwei Hashs an (mit oder ohne fuehrendes '%' Zeichen) und ein optionales Array als dritten Parameter. "hidden" erzeugt versteckte Eingabefelder fuer 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 fuer alle Werte, die an dieses Dokument geschickt wurden (in %fdat stehen), verstecke Eingabefelder, soweit dafuer nicht schon andere Eingabefelder existieren. Dies ist nuetzlich, 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>

var Das "var" Meta-Command definert eine oder mehrere Variablen zur Benutzung innerhalb dieser Embperlseite und setzt das strict Pragma. Die Variablennamen muessen 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.

sub (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 Zustaende (Optionen, Debugflags etc.) wieder auf die Werte vor dem Aufruf zuruecksetzt. Ausserdem ist es moeglich mittels "Execute" rekursive Funktionsaufrufe zu implementieren.

    Es ist ebenfalls moeglich Parameter an eine Embperl-Funktion zu uebergeben:

      [$ sub foo $]
        [- $p = shift -]
        <p> Hier zeigen wir den ersten Parameter [+ $p +]</p>
      [$ endsub $]

      [- foo ('value') -]

    Wenn Sie eine Reihe von oft benoetigten Funktionen haben, koennen 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 koennen.

  HTML Tags
Embperl behandelt die folgenden HTML Tags speziell.

TABLE, /TABLE, TR, /TR
    Embperl kann dynamische Tabellen erzeugen (ein- oder zweidimensional). Dazu ist es lediglich noetig, eine Zeile oder Spalte anzugeben, Embperl expandiert die Tabelle so weit wie noetig. Dies geschieht durch die Benutzung der "magischen" Variablen $row, $col oder $cnt. Solange Sie nicht eine der drei Variablen innerhalb einer Tabelle benuetzen, laesst Embperl die Tabelle unveraendert.

    Embperl ueberprueft 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 zurueck gibt. Aller Text zwischen <TR> und </TR> wird wiederholt, wenn die Variable $col benutzt wird und der Block, indem sie vorkommt, einen definierten Rueckgabewert hat. Rueckgabewert 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 fuer 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 Schluessel von %ENV enthaelt) an, so dass alle Umgebungsvariablen (wie im Beispiel zu while) angezeigt werden. Dabei enthaelt die erste Spalte den Index (ab Null zaehlend), die zweite Spalte den Variablennamen und die dritte Spalte den Wert der Umgebungsvariablen.

TH, /TH
    Das <TH> Tag wird als Tabellenueberschrift interpretiert. Wenn die ganze Zeile aus <TH> und </TH>, statt aus <TD> und </TD> besteht, werden die Zellen als Spaltenueberschriften interpretiert und nur einmal ausgegeben.

DIR, MENU, OL, UL, DL, SELECT, /DIR, /MENU, /OL, /UL, /DL, /SELECT
    Listen, Menues 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 fuer ein Beispiel.

OPTION
    Embperl prueft ob ein Wert fuer die entsprechende Option in den Formulardaten (%fdat) vorhanden ist. Wenn ja wird die Option als ausgewaehlt angezeigt.

    Beispiel:

        <FORM METHOD="POST">
          <P>Select Tag</P>

          Wenn Sie dieses Dokument mit list.htm?SEL1=x aufrufen,
          koennen Sie die Option bestimmen, die angewaehlt erscheint.

          <P><SELECT NAME="SEL1">
             <OPTION VALUE="[+ $v[$row] +]">
                [+ $k[$row] +]
             </OPTION>
          </SELECT></P>
        </FORM>

INPUT
    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 Schluessel und ihrem Wert, gespeichert. Fuer Radiobuttons und Checkboxen ("TYPE=RADIO" und "TYPE=CHECKBOX"), wird das "CHECKED" Attribute eingefuegt, wenn der Wert des "VALUE" Attributes mit dem Wert in %fdat uebereinstimmt, 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.

TEXTAREA, /TEXTAREA
    Das "TEXTAREA" Tag wird genau wie ein normales "INPUT" Tag behandelt (siehe oben)

META HTTP-EQUIV= ...
    "META HTTP-EQUIV= ... " ueberschreibt 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 koennen 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"); -]

A, EMBED, IMG, IFRAME, FRAME, LAYER
    Die Ausgaben von Perlbloecken 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 Arrayreferenzen innerhalb solcher URLs zur URL Parametersyntax. Beispiel:

      [-
      %A = (A => 1, B => 2) ;
      @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">

Gueltigkeitsbereiche von Variablen und Cleanup
Der Gueltigkeitsbereich von Variablen, die mit "my" oder "local" deklariert wurden, endet am Ende des umschliessenden "[+/- ... -/+]" Blocks. Der "[+/- ... -/+]" Block verhaelt sich in dieser hinsicht wie Perls "{ ... }".

Globale Variablen (alles was nicht mittels "my" oder "local" deklariert wurde) werden am Ende jedes Request automatisch wieder geloescht (insofern verhalten sie sich wie Variablen, deren Gueltigkeitsbereich das gesamte Dokument ist). Dies verhindert Probleme mit Variablen, die ihren Wert aus dem vorangegangenen Request behalten haben. Das Cleanup wird nur fuer Variablen innerhalb des Packages, der gerade ausgefuehrten Embperlseite, durchgefuehrt, d.h. alle Variablen die ohne expliziten Packagenamen deklariert wurden. Alle Variablen in anderen Packages (z.B. andere Perl Module) bleiben gueltig.

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 eigenstaendiger Prozess ausgefuehrt werden, ist ein Cleanup bei CGI Skripten nicht noetig.

Sollen Variablen nicht am Ende des Request aufgeraeumt werden, muessen 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, koennen 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 fuer Variablen, die nicht oder zusaetzlich aufgeraeumt werden sollen, koennen mittels des Hash %CLEANUP angegeben werden.

Es ist ebenfalls moeglich eine Funktion aufrufen zulassen, wenn Embperl sein Cleanup durchfuehrt. Soweit definiert, wird die Funktion CLEANUP aufgerufen, direkt bevor die weiteren Variablen aufgeraeumt werden.

 Beispiel:

  [! sub CLEANUP { $obj -> term ; } !]

Vordefinierte Variablen
Embperl hat einige spezielle Variablen mit einer vorgegebenen Bedeutung.

  %ENV
Enthaelt die selben Umgebungsvariablen, wie bei einem CGI Skript.

  %fdat
Enthaelt alle Formulardaten, die an das Dokument gesendet wurden. Das "NAME" Attribute bildet den Schluessel und das "VALUE" Attribute den Wert des Hashelements. Dabei ist es egal, ob die Daten mittels "GET" oder "POST" uebetragen wurden. Existieren mehrere Werte mit dem selben Namen, werden diese mittels "TAB" getrennt.

Embperl unterstuetzt ebenfalls den Kodierungstyp multipart/form-data, der fuer Dateiuploads benutzt wird. Das Element in %fdat enthaelt 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 hoeher installiert ist, ist es weiterhin moeglich den Dateinamen (den lokalen Dateinamen, wie er auf seiten des Browsers heisst) und Informationen, die von der CGI.pm Funktion "uploadInfo" zur Verfuegung gestellt werden, zu erhalten. Der Dateiname ist in dem entsprechenden %fdat Element direkt enthalten. Um auf die uploadInfos zuzugreifen, muss 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 unterstuetzt wird.

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

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

  %udat (ab 1.2b1)
Sie koennen %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 naechste Embperl Seite aufruft, sendet der Browser den Cookie mit der Session Id zurueck und Embperl stellt die Daten in %udat wieder her. (siehe auch Abschnitt ueber "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 ueber "Session Handling")

  $row, $col
Reihen und Spaltenzaehler fuer dynamische Tabellen. (Siehe "HTML Table Tag".)

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

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

  $tabmode
Entscheidet, wann das Tabellenende erreicht ist.

Tabellenende:

$tabmode = 1
    Ende, wenn ein Block der $row enthaelt, "undef" als Ergebnis hat. Die Reihe, die den undefinierten Ausdruck enthaelt, wird nicht mehr angezeigt.

$tabmode = 2
    Ende, wenn ein Block der $row enthaelt, "undef" als Ergebnis hat. Die Reihe, die den undefinierten Ausdruck enthaelt, wird angezeigt.

$tabmode = 4
    Ende, wenn $maxrow Reihen angezeigt wurden.

Spaltenende:

$tabmode = 16
    Ende, wenn ein Block der $col enthaelt, "undef" als Ergebnis hat. Die Spalte, die den undefinierten Ausdruck enthaelt, wird nicht mehr angezeigt.

$tabmode = 32
    Ende, wenn ein Block der $col enthaelt, "undef" als Ergebnis hat. Die Spalte, die den undefinierten Ausdruck enthaelt, wird angezeigt.

$tabmode = 64
    Ende, wenn $maxcol Spalten angezeigt wurden.

Der Defaultwert von 17 ist korrekt zum Anzeigen von Arrays. Es duerfte selten noetig sein diesen Wert zu aendern. Die Werte fuer Tabellen- und Spaltenende koennen addiert werden.

  $escmode
Schaltet die HTML und URL Kodierung der Ausgabe ein und aus. Default ist ein ($escmode = 3).

$escmode = 3
    Das Resultat von Perlausdruecken wird HTML Kodiert (z.B. '>' wird zu '&gt;') und URL Kodiert ('&' wird zu '%26') innerhalb von "A", "EMBED", "IMG", "IFRAME", "FRAME" und "LAYER" Tags.

$escmode = 2
    Das Resultat von Perlausdruecken wird immer URL Kodiert ('&' wird zu '%26').

$escmode = 1
    Das Resultat von Perlausdruecken wird immer HTML Kodiert (z.B. '>' wird zu '&gt;').

$escmode = 0
    Keine HTML oder URL Kodierung findet statt.

  $req_rec
Diese Variable ist nur vorhanden, wenn Embperl unter mod_perl laeuft und enthaelt eine Referenz auf den Apache Request Record. Damit ist es moeglich, alle Apache internen Funktionen zu nutzen. (siehe perldoc Apache fuer weitere Informationen)

  LOG
Dies ist die Dateihandle der Embperl Logdatei. Durch schreiben auf diese Dateihandle ist es moeglich, 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, koennen Sie folgendermassen eine Dateihandle dafuer 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 zuuebergeben oder zurueckzugegben. (siehe Execute)

  %http_headers_out (ab 1.2b10)
Dieser Hash ermoeglicht 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/" -]

siehe auch "META HTTP-EQUIV= ..."

  $optXXX $dbgXXX
Alle Optionen (see "EMBPERL_OPTIONS") und alle Debugflags (siehe "EMBPERL_DEBUG") koennen 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 koennen. Das Setzen solcher Optionen ist nur in den Konfigurationsdateien moeglich. Folgende Optionen koennen nur gelesen werden:

$optDisableVarCleanup
$optSafeNamespace
$optOpcodeMask
$optDisableChdir
$optEarlyHttpHeader
$optDisableFormData
$optAllFormData
$optRedirectStdout
$optAllowZeroFilesize
$optKeepSrcInMemory

  %CLEANUP
Embperl raeumt nur Variablen auf, die innerhalb der Embperl Seite definiert wurden. Sollen weitere Variablen aufgeraeumt werden, koennen diese dem Hash %CLEANUP, mit dem Variablennamen als Schluessel und einem Wert von 1, hinzugefuegt werden. Umgedreht ist es moeglich das Aufraeumen zu verhindern, wenn der Variablennamen mit einem Wert von 0 hinzugefuegt wird.

Session Handling (ab 1.2b2)
Embperl ist in der Lage, Daten pro Benutzer fuer Sie zu verwalten. Sobald Sie Daten in den Hash %udat schreiben, sorgt Embperl dafuer, dass die selben Daten wieder verfuegbar sind, sobald der selbe Benutzer eine weitere Seite aufruft.

Weiterhin koennen 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 ueber Prozess- oder sogar Rechnergrenzen hinweg moeglich. Embperl bedient sich dazu des Perlmodules Apache::Session.

Um das Session Management zu aktivieren muss Apache::Session (Version 1.00 oder hoeher) installiert sein. Ausserdem muessen Sie Embperl, via "EMBPERL_SESSION_ARGS", mitteilen, welcher Speicher- und Lockingmechanismus genutzt werden soll, ggf. muessen Sie auch weitere Argumente fuer Apache::Session setzen. Eine Beispiel startup.pl Datei, koennte folgendermassen aussehen:

 BEGIN
    {
    $ENV{EMBPERL_SESSION_CLASSES} = "DBIStore SysVSemaphoreLocker" ;
    $ENV{EMBPERL_SESSION_ARGS}    = "DataSource=dbi:mysql:session UserName=test" ;
    } ;
 use HTML::Embperl ;

Fuer Solaris ist es bei der Benutzung von SysVSemaphoreLocker noetig zusaetzlich das "nsems" Argument zu setzen:

 $Apache::Session::SysVSemaphoreLocker::nsems = 16;

Dass selbe kann auch direkt in die httpd.conf eingetragen werden:

 PerlSetEnv EMBPERL_SESSION_CLASSES "DBIStore SysVSemaphoreLocker"
 PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=test"
 PerlModule HTML::Embperl ;

"EMBPERL_SESSION_ARGS" ist eine Leerzeichen separierte Liste von Name/Wert Paaren die zusaetzlich Parameter fuer die Apache::Session Klassen angeben koennen.

HINWEIS: Die obige Konfiguration funktioniert nur mit Embperl 1.2b11 oder hoeher. Aeltere Konfigurationen mit Apache::Session werden weiterhin unterstuetzt, die Dokumentation dazu jedoch entferent. Es ist nun nicht mehr noetig Apache::Session vor Embperl zu laden. Bitte beachten Sie das Apache::Session 0.17 und 1.xx nicht kompatibel zueinander sind und eine andere Konfiguration erfordern.

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. Fuer Benutzerbezogene Session wird diese Id mittels eines Cookies zum Browser gesandt. Ausserdem veranlasst Embperl Apache::Session die Daten zu speichern. Empfaengt Embperl einen solchen Cookie mit einer Id, wird diese zunaechst nur abgespeichert, erst bei einem Zugriff auf %udat, werden die Daten tatsaechlich von Apache::Session angefordert. Ebenso werden die Daten fuer %mdat erst von Apache::Session angefordert, wenn auf diesen Hash zugegriffen wird.

(Sichere-)Namensraeume und Opcode Restriktionen
Da die meisten Web Server mehr als ein Dokument verwalten, ist es noetig, die Dokumente gegeneinander zu schuetzen. Embperl benutzt dazu Perl Namensraeume (Packages). Standardmaessig fuehrt Embperl jedes Dokument in seinem eigenen Namensraum aus. Das verhindert, das globale Variablen, sich gegenseitig ueberschreiben oder beeinflussen. Mittels der Konfigurationsanweisung EMBPERL_PACKAGE ist es moeglich einen expliziten Packagenamen fuer ein oder mehere Dokumente vorzugeben. Dies alles verhindert aber nicht, das durch die Angabe eines Variablennamen incl. Packagenamen eine Embperlseite auf andere Namensraeume zugreifen kann.

Manchmal, z.B. wenn mehrere Personnen Zugriff auf die Webserverinhalte haben sollen, ist es notwendig Dokumente tatsaechlich gegenseitig zuschuetzen. Fuer solche Faellen kann Embperl Safe.pm nutzen um sichere Namensraeume bereit zu stellen. Ein Dokument, das in einem solchen sicheren Namensraum ablaeuft, kann dann nicht mehr auf andere Namensraeume zugreifen. (Fuer weitere Informationen zu sicheren Namensraeumen lesen Sie bitte die Dokumentation zu Safe.pm)

Um ein Dokument in einem sicheren Namensraum ablaufen zu lassen, muessen Sie lediglich die Option optSafeNamespace setzen. Der Packagename wird dabei weiterhin automatisch von Embperl erzeugt oder kann mittels EMBPERL_PACKAGE gesetzt werden.

HINWEIS: Fuer das ausgefuehrte Dokument erscheint es so, als wuerde der Code im Package main ausgefuehrt!

Eine weitere Moeglichkeit, um Embperl Seiten sicher zu machen, ist die Benutzung von Opcode Restriktionen. Dazu ist es noetig, 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 spaeter verwendet, damit Embperl weiss, welches Compartment es benutzen soll). Nun koennen Sie die Opcode Maske aendern. Zum Beispiel:

 B<$cp->deny(':base_loop');>

In Ihrer Konfiguration muessen 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 ausgefuehrt. 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, ausgefuehrt.

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.

Utility Funktionen

  AddCompartment($Name)
Fuegt 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 zurueck, so dass die Methoden zum Freigeben oder Sperren bestimmter Opcodes aufgerufen werden koennen. (siehe auch "(Sichere-)Namesraeume 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 eintraegt.

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 muss 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 muessen Net::SMTP (aus dem libnet Package) installiert haben, wenn Sie diese Funktion nutzen wollen.

  exit
"exit" ueberschreibt die standard Perl "exit" Funktion. "exit" beendet die Ausfuehrung des Dokuments und sendet alle bis dahin ausgefuehrten 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 Childprozess beendet. "Apache::exit" fuehrt dazu, dass die Ausfuehrung des Moduls, wie auch der Embperl Seite, abgebrochen wird, jedoch alle Ausgaben noch zum Browser gelangen.

Ein-/Ausgabefunktionen

  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 wuerde eine Anfrage fuer "/embperl/ifunc/foo.html" z.B. die URL "http://otherhost/otherpath/foo.html" als Quelle fuer die Bearbeitung durch Embperl verwenden.

Eine moegliche Anwendung ist, die Ausgabe von mod_include durch Embperl weiter bearbeiten zu lassen.

Beispielkonfiguration in srm.conf fuer 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 muessen 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 ausgefuehrt wird. Die resultierende Seite wird dann von Embperl weiterverarbeitet. Es ist ebenfalls moeglich zwei unterschiedliche Ports fuer 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 erhoeht wird.

Inside Embperl - Wie der Embedded Perl Code intern ausgefuehrt wird
Wenn Embperl auf einen Block mit Perl Code trifft
  ([+/-/!/$ .... $/!/-/+]) fuehrt es folgende Bearbeitungsschritte aus:

1. Alles, was wie ein HTML Tag aussieht, entfernen.
2. Transformieren HTML/URL kodierter Zeichen in entsprechende ASCII Zeichen.
3. Entfernen aller Carriage Returns.
4. Uebersetzen des Perl Codes als eigenstaendige Funktion.
5. Aufrufen der Funktion.
6. URL/HTML kodieren von entsprechenden Sonderzeichen im Rueckgabewert.
7. Senden des Rueckgabewertes (an Browser oder Datei etc.)

Die Schritte 1-4 werden nur beim ersten Mal, wenn Embperl auf den Perl Code trifft, ausgefuehrt. Wird die Seite das zweite mal abgerufen, bzw. liegt der Block in einer Schleife, muss Embperl lediglich die vorkompilierte Funktion aufrufen.

Schritte 6 und 7 werden nur bei Ausgaben, d.h. "[+ ... +]" Bloecken, ausgefuehrt.

  Was bedeutet das im Detail?
Als Beispiel nehmen wir folgenden Code:

 [+ <BR>
 $a = "Dies '&gt;' ist ein  Groesserzeichen"
 <BR> +]

  1. Entfernen der HTML Tags. Danach sieht es folgendermassen aus:
 [+
 $a = "Dies '&gt;' ist ein  Groesserzeichen"
 +]

Die <BR>'s in diesem Fall machen keinen Sinn, sie kommen hoechstwahrscheinlich von einem WYSIWYG HTML Editor, dadurch das der Benutzer zur besseren Uebersicht hier eine neue Zeile beginnen wollte. Solche Editoren fuegen u.U. auch ungewollte Tags wie "<FONT"> o.ae. 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 zerstoeren koennen.

Es gibt auch Faelle, wo HTML Tags wirklich gebraucht werden. Zum Beispiel: Nehmen wir an, Sie wollen folgendes Ausgeben:

 [+ "<FONT COLOR=$col>" +]

Ohne weitere Massnahmen, wuerde Embperl folgendes daraus machen:

 [+ "" +]

Um aber dennoch HTML Tags zu verwenden gibt es verschiedene Moeglichkeiten:

a. <FONT COLOR=[+$col+]>
    Schreiben Sie nur den wirklich notwendigen Teil innerhalb des "[+ ... +]" Blocks und verlagern sie das HTML Tag nach ausserhalb. Dies ist der unproblematischste Weg und sollte wenn immer moeglich gewaehlt werden.

b. [+ "\<FONT COLOR=$col>" +]
    Durch Voranstellen eines Backslashs ('\').

c. [+ "&lt;FONT COLOR=$col&gt;" +]
    Sie koennen HTML kodierte Zeichen benutzen. Die meisten HTML Editoren machen dies automatisch. (In diesem Fall brauchen Sie sich nicht weiter darum zu kuemmern.)

d. Die Option "optRawInput" setzen.
    Dies verhindert grundsaetzlich das Entfernen von HTML Tags.

HINWEIS: In den Faellen b-d sollten Sie ebenfalls die Ausgabe-HTML-Kodierung beachten (siehe unten).

Zu beachten ist ebenfalls, dass Embperl den Perl Dateihandle Operator (<>) als HTML Tag interpretiert und ihn damit entfernt.

Anstelle von

  [- $line = <STDIN>; -]

sollten Sie eine der folgenden Schreibweise verwenden:

a. [- $line = \<STDIN>; -]
b. [- $line = &lt;STDIN&gt;; -]

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, uebersetzt Embperl dies zu "$a < $b". Nehmen wir das Beispiel von vorhin, dann sieht es jetzt so aus:

 [+
 $a = "Dies '>' ist ein Groesserzeichen"
 +]

Dies dient wiederum der Unterstuetzung von High-Level Editoren. Dadurch ist es unerheblich, wenn Ihr Editor "&gt;" statt > im Quellentext schreibt.

Auch hier ist es manchmal noetig, die HTML kodierten Zeichen zu erhalten. Dazu bietet Embperl folgende Moeglichkeiten:

a. \&gt;
    Durch Voranstellen eines Backslashs ('\').

b. &amp;gt;
    Schreiben Sie das erste '&' als HTML kodiertes Zeichen (&amp;). Ein HTML Editor wird dies von sich machen, wenn Sie "&gt;" als Text eingeben.

c. Die Option "optRawInput" setzen.
    Dies verhindert grundsaetzlich 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 vollstaendig zu sperren. Durch setzen von optRawInput in EMBPERL_OPTIONS laesst Embperl den Perl Code unberuehrt. Diese Option sollten Sie setzen, wenn Sie einen ASCII Editor benutzen, bei Benutzung eines HTML Editors, sollte diese Option nicht noetig sein.

Sie koennen optRawInput auch innerhalb Ihres Dokument ein-/ausschalten, indem Sie $optRawInput 1 oder 0 zuweisen, wobei zu beachten ist, dass die Aenderung erst ab dem naechsten Block wirksam wird. Beispiel:

 [- $optRawInput = 1 -]
 [- $line = <FILEHANDLE> -]

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

  4. Uebersetzen des Perl Codes als eigenstaendige Funktion.
Der naechste Schritt generiert eine Funktion aus Ihrem Perl Code. Das obige Beispiel sieht danach wie folgt aus:

sub foo
    {
    $a = "Dies '>' ist ein Groesserzeichen"
    }

Die Funktion wird vom Perlinterpreter in einem internen vorkompilierten Format gespeichert und kann somit spaeter immer wieder aufgerufen werden, ohne die Schritte 1-4 wiederholen zu muessen. Embperl erkennt, wenn das gleiche Dokument ein zweites mal angefordert wird und ruft lediglich die bereits kompilierte Funktion auf. Dadurch wird auch die Ausfuehrung 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 tatsaechlich auszufuehren.

Falls nicht ein "[+ ... +]" Block ausgefuehrt wird, ist die Bearbeitung damit abgeschlossen.

  6. URL/HTML kodieren von entsprechenden Sonderzeichen im Rueckgabewert.
Unser Beispiel erzeugt die Zeichenkette:

 "Dies '>' ist ein Groesserzeichen"

Das Groesserzeichen hier ist normaler Text (und nicht das Ende eines HTML Tags), gemaess HTML Spezifikation muss es als "&gt;" zum Browser gesendet werden. In vielen Faellen entsteht kein Problem, wenn man direkt das Groesserzeichen sendet, da der Browser hoechstwahrscheinlich das '>' als normalen Text ausgeben wird. In diesem Fall waere es auch moeglich gleich "&gt;" in unseren Perl Code schreiben, wenn jedoch die Zeichenkette z.B. Ergebnis einer Datenbankabfrage ist und/oder nationale Sonderzeichen enthaelt, ist es notwendig eine HTML Kodierung der Zeichen durchzufuehren.

Weiterhin werden Tags, die URLs enthalten (wie "<A"> oder "<FRAME">), insofern speziell behandelt, als dass Ausgaben innerhalb des Parameters der die URL enthaelt, URL kodiert werden. (z.B. wird '&' zu %26 und Leerzeichen zu '+'). Dies ist noetig, damit der Browser Sonderzeichen korrekt interpretiert.

Beispiel:

   <A HREF="http://host/script?name=[+$n+]">

Falls $n den Wert "Mein Name" enthaelt, wird die resultierende URL:

   http://host/script?name=Mein+Name

In einigen Faellen ist es nuetzlich, die Ausgabekodierung abzuschalten. Dies kann mit der Variablen $escmode geschehen.

Beispiel: (Um das Beispiel einfacher lesbar zu machen, setzen wir voraus, dass "optRawInput" gesetzt ist. Andernfalls sind die in 1 - 3 beschriebenen Punkte zu beachten)

    [+ "<FONT COLOR=5>" +]

Dies wuerde zum Browser als "&lt;FONT COLOR=5&gt;" gesandt, was dazu fuehrt das der Tag exakt so auf dem Bildschirm zusehen ist, statt das sich die Farbe des folgenden Textes aendert.

    [+ 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 fuer alle Ausgaben, innerhalb des Blocks. Moechten Sie $escmode hin- und herschalten, muessen Sie mehrere "[+ ... +]" Bloecke verwenden.

  7. Senden des Rueckgabewertes (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 vollstaendigen Ausfuehrung des Dokuments zwischengespeichert. Ist das ganze Dokument abgearbeitet, werden zuerst alle HTTP Header gesendet (dies erlaubt waehrend der Erstellung des Dokuments zusaetzliche HTTP Header hinzuzufuegen) und anschliessend der eigentliche Inhalt. Tritt waehrend der Verarbeitung ein Fehler auf, wird statt dem Inhalt eine Fehlerseite zum Browser gesandt.

Performance
Um die beste Performance von Embperl zu erzielen, ist es notwendig, das Logging auf ein Minimum zu beschraenken. Sie koennen Embperl drastisch verlangsamen, wenn Sie alle Logging Option einschalten. Vorallem sollten Sie niemals dbgFlushOutput, dbgFlushLog oder dbgCacheDisable auf einen Produktionsserver einschalten. Waehrend der geringfuegige Performanceverlust beim Debuggen nicht auffaellt, 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 fuer weitere Ideenen zur Performancesteigerung.

Bugs
Fehler sind keine bekannt.

Es wird jedoch empfohlen mindestens Perl 5.004_04 und mod_perl 1.08 einzusetzen, da aeltere Versionen Speicherlecks aufweisen.

Kompabilitaet
Embperl wurde erfolgreich getestet

  unter Linux 2.x mit

perl5.004_04
perl5.005_03
apache_1.2.5
apache_1.2.6
apache_1.3.0
apache_1.3.1
apache_1.3.2
apache_1.3.3
apache_1.3.4
apache_1.3.5
apache_1.3.6
Apache_1.3.9
apache_ssl (Ben SSL)
Stronghold 2.2
Stronghold 2.4.1
Apache_1.3.3 with mod_ssl 2.0.13
Apache_1.3.6 with mod_ssl 2.3.5

Rueckmeldungen bestaetigen, dass es ebenfalls auf fast allen anderen Unix Varianten problemlos laeuft.

  unter Windows NT 4.0 mit

perl5.004_04
perl5.005
apache_1.3.1
apache_1.3.6
Apache_1.3.9

  unter Windows 95/98 mit

perl5.004_02 (Binary Distribution, nur Offline Mode)
perl5.005_02 + apache_1.3.6

Support

  Rueckmeldungen/Anregungen/Probleme/Fehlerreports
Diskussionen zu allen Fragen/Problemen rund um Embperl werden auf der mod_perl Mailingliste gefuehrt. Sollten Sie Probleme mit Embperl haben, die sich nach der Lektuere dieser Dokumentation sowie der FAQs nicht loesen 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://outside.organic.com/mail-archives/modperl/
 http://forum.swarthmore.edu/epigone/modperl

Um die Mailingliste zu abbonieren, senden Sie eine Mail an majordomo@apache.org mit dem Text "subscribe modperl" als Text.

  Kommerzieller Support
ecos bietet die Moeglichkeit, Support fuer Embperl zu kaufen. Dies umfasst:

•   Beratung und Unterstuetzung Ihrer Programmierer

•   Konzeptionierung und Plannung von dynamischen Websites

•   Erstellung von teilweisen oder kompletten Webangeboten

•   Beseitigung von Fehler in Embperl (auch fuer mod_perl und Apache)

•   Implementierung neuer Features

Sie erreichen uns via http://www.ecos.de oder info@ecos.de

Links

  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       http://www.perl.com/CPAN/authors/Jeffrey_Baker/

  CVS
Die aktuelle Entwicklerversion ist via CVS verfuegbar. Weitere Informationen dazu stehen in "perldoc CVS.pod".

Author
G. Richter (richter@dev.ecos.de)

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 9:
    Non-ASCII character seen before =encoding in 'einzufuegen.'. Assuming ISO8859-1