in einem
Block zu schreiben und die abschließenden Klammer ('}') in einem anderen Block.
Dies ist nur mit L<[* Perl Code *]> Blöcken möglich.
```
**HINWEIS:** Um Perlfunktionen zu definieren, benutzen Sie the section on *\[! Perl Code !\]* (siehe unten) da dies vermeidet, dass die Funktion bei jedem Aufruf neu übersetzt wird.\
**\[! Perl Code !\]** Wie the section on *\[- 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 the section on `[- 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 the *Execute* manpage 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 the section on `[- Perl Code -]` Blöcke hinziehen, jedoch sehr wohl über mehrere the section on `[* Perl Code *]` Blöcke. Beispiel:
```
[* foreach $i (1..10) { *]
[- $a = $i + 5 -]
Schleifenzähler + 5 = [+ $a +]
```
```
[* } *]
```
Folgendes hingegen funktioniert **nicht**:
```
[- foreach $i (1..10) { -]
irgendwelcher Text
[- } -]
```
Der selbe Effekt kann mit *Embperl* Meta Commands erzielt werden (siehe unten)
```
[$ foreach $i (1..10) $]
[- $a = $i + 5 -]
Schleifenzähler + 5 = [+ $a +]
```
```
[$ 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
[$ else $]
Andere Methode als GET wurde benutzt
[$ 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 < $#k) $]
[+ $k[$i] +] = [+ $ENV{$k[$i]} +]
[- $i++ -]
[$ endwhile $]
```
Dies sendet alle Umgebungsvariablen zum Browser.
**HINWEIS**: '<' wird zu '\<' bevor es vom Perlinterpreter ausgeführt wird, außer the *optRawInput* manpage ist gesetzt.\
Führt eine Schleife aus, bis **Arg** des **until** Befehls *wahr* ist.
Beispiel:
```
[- $i = 0 -]
[$ do $]
[+ $i++ +]
[$ 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 +]
[$ 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)
```
```
Wenn Sie dieses Dokument mit
http://host/doc.htm?field1=A&field2=B&field3=C
aufrufen, erzeugt *Embperl* folgende Ausgabe:
```
```
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 $]
Hier steht was
[$ endsub $]
```
Diese Funktion kann entweder als normale Perlfunktion aufgerufen werden:
```
[- foo -]
```
oder mittels der the *HTML::Embperl::Execute* manpage 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 -]
Hier zeigen wir den ersten Parameter [+ $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 \ und \, solange der Block in dem `$row` oder `$cnt` enthalten sind, ein Ergebnis ungleich *undef* zurück gibt. Aller Text zwischen \ und \ 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 the section on *$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 -]
| [+ $i=$row +] |
[+ $k[$row] +] |
[+ $ENV{$k[$i]} +] |
```
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 \ Tag wird als Tabellenüberschrift interpretiert. Wenn die ganze Zeile aus \ und \, statt aus \ und \ besteht, werden die Zellen als Spaltenüberschriften interpretiert und nur einmal ausgegeben.\
Listen, Menüs und Listboxen werden genau wie eindimensionale Tabellen behandelt. Nur the section on *$row*, the section on *$maxrow*, the section on *$col*, the section on *$maxcol* und the section on *$tabmode* werden beachtet, the section on *$col* und the section on *$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:
```
```
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:
```
```
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 the section on *$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)
-]
```
```
```
wird von *Embperl* zu Folgendem expandiert:
```
```
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 the *EMBPERL\_PACKAGE* manpage 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 the *EMBPERL\_OPTIONS* manpage bzw. dem the *cleanup* manpage Parameter der the *Execute* manpage Funktion abgeschaltet werden. Ausnahmen für Variablen, die **nicht** oder zusätzlich aufgeräumt werden sollen, können mittels des Hash the section on *%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:
```
```
Embperl ACTION:
```
[- if (defined $fdat{ImageName}) {
open FILE, "> /tmp/file.$$";
print FILE $buffer
while read($fdat{ImageName}, $buffer, 32768);
close FILE;
}
-]
Wenn I 2.46 oder höher installiert ist, ist es weiterhin möglich den
Dateinamen (den B Dateinamen, wie er auf seiten des Browsers heißt)
und Informationen, die von der I Funktion C zur Verfügung
gestellt werden, zu erhalten. Der Dateiname ist in dem entsprechenden
C<%fdat> Element direkt enthalten. Um auf die B 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} +]
Content-Type: [+ $fdat{-ImageName} -> {'Content-Type'} +]
```
**HINWEIS:** Der Zugriff auf die **Upload-Infos** erfolgte vor 1.2b11 auf andere Art und Weise, die nicht mehr unterstützt wird.\
`@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).\
Das Resultat von Perlausdrücken wird HTML Kodiert (z.B. '\>' wird zu '>') 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 '>').\
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/" -]
```
siehe auch the section on *META HTTP-EQUIV= ...*\
`$optXXX` `$dbgXXX` Alle Optionen (see the section on *EMBPERL\_OPTIONS*) und alle Debugflags (siehe the section on *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. *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_ARGS`, mitteilen, welcher Speicher- und Lockingmechanismus genutzt werden soll, ggf. müssen Sie auch weitere Argumente für *Apache::Session* setzen. Eine Beispiel *startup.pl* Datei, könnte folgendermaßen aussehen:
```
BEGIN
{
$ENV{EMBPERL_SESSION_CLASSES} = "DBIStore SysVSemaphoreLocker" ;
$ENV{EMBPERL_SESSION_ARGS} = "DataSource=dbi:mysql:session UserName=test" ;
} ;
use HTML::Embperl ;
```
Für **Solaris** ist es bei der Benutzung von SysVSemaphoreLocker nötig zusätzlich 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 zusätzlich Parameter für die *Apache::Session* Klassen angeben können. **HINWEIS:** Die obige Konfiguration funktioniert nur mit *Embperl* 1.2b11 oder höher. Ältere Konfigurationen mit *Apache::Session* werden weiterhin unterstützt, die Dokumentation dazu jedoch entferent. Es ist nun nicht mehr nötig *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. 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. 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 the *EMBPERL\_PACKAGE* manpage 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 the *optSafeNamespace* manpage setzen. Der Packagename wird dabei weiterhin automatisch von *Embperl* erzeugt oder kann mittels the *EMBPERL\_PACKAGE* manpage 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 the *optOpcodeMask* manpage in the *EMBPERL\_OPTIONS* manpage setzen und spezifizieren aus welchem Compartment die Opcode Maske (durch setzen von the *EMBPERL\_COMPARTMENT* manpage) genommen werden soll. Beispiel (beim Gebrauch mit mod\_perl):
```
B
```
```
PerlScript startup.pl
```
```
SetEnv EMBPERL_DEBUG 2285
```
```
Alias /embperl /path/to/embperl/eg
```
```
SetHandler perl-script
PerlHandler HTML::Embperl
Options ExecCGI
PerlSetEnv EMBPERL_OPTIONS 12
PerlSetEnv EMBPERL_COMPARTMENT test
```
```
B
```
```
$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 the section on *(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:
```