=pod

=head1 NAME

Embperl - Erstellen dynamischer Websites mit Perl

=head1 SYNOPSIS

=head1 DESCRIPTION

Embperl ist ein System zum Erstellen dynamischer Websites mit Perl.

Für den Anfänger ist es ein einfacher Weg um dynamische Seiten 
durch Einbetten von Perlcode in HTML zu erstellen.
Es stellt verschiedenste Features für das Webumfeld zur Verfügung, wei z.B.
dynamischen Tabellen, Formularfeldverarbeitung, HTML/URL-Kodierung, Session Handling, 
Caching und mehr.

Wenn die Anforderungen steigen ermöglicht es die Website objektorientiert,
aus kleinen wiederverwendbaren Komponenten, aufzubauen. Wenn Sie Code und 
Layout nicht mixen wollen, unterstützt Sie Embperl, indem es erlaubt beides
in verschiedene Objekte zu trennen (um z.B. MVC Applikationen zu bauen).
Selbstverständlich kann Embperl nicht nur HTML verarbeiten, sondern ist in der Lage 
Komponenten in verschiedenen Quellenformaten (z.B. HTML, WML, XML, POD, ...)
zu bearbeiten und diese, soweit nötig, in andere Ausgabeformate (z.B. via XSLT)
zu transformieren. Dies wird dadurch erreicht, das die Ausgabeerzeugung in
kleine Schritte zerlegt wird, wovon jeder von einem austauschbaren Provider
bearbeitet wird.

Für fortgeschrittenen Anwender bietet Embperl weitere Möglichkeiten, wie
das Erstellen von eigenen Grammatiken (z.b. Tag-Bibiliotheken) oder das
schreiben von benutzerspezifischen Providern.



=head1 Syntax

Embperl versteht zwei Katagorien von Befehlen. Die erste Kategorie sind
spezielle I<Embperl> Befehle, die zweite besteht aus einer Reihe von
HTML Tags, die spezielle Funktionen anstoßen.

Bevor I<Embperl> Befehle bearbeitet (ebenso für Argumente von HTML Tags,
die von I<Embperl> bearbeitet werden), werden alle HTML Tags, die sich innerhalb des
Perlcodes befinden, entfernt und HTML kodierte Zeichen werden in ihre Ascii
Äquvivalente umgewandelt, so daß sie der Perlinterpreter versteht.
Dies ist nötig, um HTML Seiten, die von (WYSIWYG) HTML-Editoren erzeugt werden,
zu verarbeiten. (z.B. um ein <BR> innerhalb des Perlcodes zu entfernen, welches
der HTML Editor in den Perlcode eingefügt hat, an einer Stelle, wo lediglich ein
Zeilenumbruch sein sollte.) 
Um dieses zu unterbinden, können HTML Tags und HTML kodierten Zeichen (beides nur
innerhalb des Perlcodes) ein Backslash ('\') vorangestellt werden.

B<WICHTIGER HINWEIS:> Wenn Sie einen Ascii Editor benutzen, um Ihre HTML Dokumente
zu schreiben, sollten Sie die Option L<optRawInput> setzen. Dies verhindert das 
I<Embperl> den Quellentext in der oben beschriebenen Weise vorverarbeitet.

B<Sollten Sie Probleme mit Ihrem Code haben, speziell mit HTML Tags oder
Dateihandles, versichern Sie sich, daß Sie die Ein- und Ausgabekodierung und
-dekodierung, die Embperl durchführt, verstanden haben. Weitere Hinweise finden sich
im Abschnitt L<"Inside Embperl"|"Inside Embperl - Wie der Embedded Perl Code intern ausgeführt wird">
und in den FAQs.>

Alle I<Embperl> Befehle fangen mit einer eckigen Klammer ('[') an und Enden mit
der geschlossenen eckigen Klammer (']'). Um eine normale '[' im HTML Text zu erhalten,
ist es nötig '[[' zu schreiben.

I<Embperl> benutzt keine HTML Kommentare (z.B. <! ... !>) oder andere spezielle
HTML Tags, da es mit manchen HTML Editoren nicht, oder nur sehr umständlich,
möglich ist, diese zu erzeugen. Da '[' von den HTML Editoren als normaler Text interpretiert wird,
sollte es damit keinerlei Probleme geben, es vereinfacht in den meisten Fällen das schreiben 
der Dokumente erheblich.


=head2 [+ Perl Code +]

Ersetzt den Befehl durch das Resultat der Ausführung des Perl codes.
C<Perl Code> kann dabei beliebiger Perl code sein.

Beispiel:


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

 [+ $a+1 +]      Beliebige Ausdrücke können benutzt werden.

 [+ $x[$i] +]    Auch Arrays, Hashs oder komplexere Ausdrücke sind kein Problem

B<HINWEIS:> Leerzeichen werden ignoriert.  Die Ausgabe wird automatisch HTML kodiert
(z.B. wird '<' zu '&lt;'). Die Ausgabekodierung kann mit der Variablen
L<$escmode> gesteuert werden.


=head2 [- Perl Code -]

Führt den C<Perl Code> aus. In der Ausgabe wird dieser Befehl jedoch vollständig entfernt.

Beispiel:

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

 [- use SomeModule -]  Andere Perlmodule können genutzt werden.

 [- $i=0; while ($i<5) {$i++} -]  Auch komplexer Code kann verwendet werden.
 
B<HINWEIS:> Perlbefehle, wie C<if>, C<while>, C<for>, etc., müssen innerhalb eines
I<Embperl> Blockes abgeschlossen werden. Es ist nicht möglich das C<if> 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.

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


=head2 [! Perl Code !]

Wie L<[- 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.


=head2 [* Perl Code *]

(ab 1.2b2)

Ähnlich wie L<C<[- Perl Code -]>>. Der Hauptunterschied ist, daß C<[- Perl Code -]> Blöcke immer
ihren eigenen Gültigkeitsbereich haben, während C<[* Perl Code *]> Blöcke im selben 
Gültigkeitsbereich ablaufen.
Dies ermöglicht lokale Variablen (mit C<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 I<Embperl> Seite rekursiv mittes L<Execute>
aufzurufen), ist es jedoch hilfreich.

Ein zweiter Grund ist, die Möglichkeit Perlbefehle zu nutzen, die sich über
mehrere Blöcke hinziehen. Perls C<if>, C<while>, C<for>, etc. können sich
nicht über mehrere L<C<[- Perl Code -]>> Blöcke hinziehen, jedoch sehr wohl
über mehrere L<C<[* Perl Code *]>> Blöcke.

Beispiel:

  [* foreach $i (1..10) { *]
    
    [- $a = $i + 5 -]
    Schleifenzähler + 5 = [+ $a +] <br>

  [* } *]

Folgendes hingegen funktioniert B<nicht>:

  [- foreach $i (1..10) { -]
    irgendwelcher Text <br>
  [- } -]

Der selbe Effekt kann mit  I<Embperl> L<Meta Commands|"[$ Cmd Arg $]  (Meta-Commands)">
erzielt werden (siehe unten)

  [$ foreach $i (1..10) $]
    
    [- $a = $i + 5 -]
    Schleifenzähler + 5 = [+ $a +] <br>

  [$ endforeach $]

B<HINWEIS 1:> C<[* ... *]> Blöcke B<müssen> immer mit B<;>,B<{> oder B<}> enden!

B<HINWEIS 2:> C<[* ... *]> Blöcke können nicht innerhalb eines HTML Tags, welches
von I<Embperl> interpretiert wird, verwendet werden.
(Außer die Bearbeitung des entsprechden Tags wurde ausgeschaltet)

B<HINWEIS 3:> Da die Ausführung von C<[- ... -]> Blöcken durch I<Embperl> gesteuert
wird, kann I<Embperl> deutlich detailliertere debugging Ausgaben in der Logdatei
dafür erzeugen. Außerdem existieren für C<[- ... -]> keinerlei Restriktionen, wo sie
genutzt werden können.


=head2 [# Text #]  (Kommentar)

(ab1.2b2)

Dies ist ein Kommentarblock. Alles zwischen C<[#> und C<#]> wird aus dem HTML Dokument
entfernt, bevor es zum Browser gesandt wird.

B<HINWEIS 1:> C<[* ... *]> Blöcke werden vor Kommentarblöcken ausgewertet, deshalb werden
sie auch innerhalb von Kommentarblöcken ausgeführt.

B<HINWEIS 2:> Alles innerhalb des Komentarblocks (außer C<[* ... *]>) wird aus dem Quellentext entfernt,
deshalb ist es möglich, Teile des Dokuments damit auszukommentieren.


=head2 [$ Cmd Arg $]  (Meta-Commands)

Ausführen eines I<Embperl> Meta-Commands.  B<Cmd> kann einer der folgenden
Befehle sein:
(B<Arg> variiert, je nach Befehl).

=over 4

=item B<if>, B<elsif>, B<else>, B<endif>

Alles nach dem B<if> Meta-Command bis zum B<else>,
B<elsif> oder B<endif> wird nur ausgegeben, wenn der Perlausdruck, welcher durch
B<Arg> gegeben ist, I<wahr> ist.  B<else> und B<elsif> funktionieren entsprechend.

Beispiel:

 [$ if $ENV{REQUEST_METHOD} eq 'GET' $]
 Methode ist GET<BR>
 [$ else $]
 Andere Methode als GET wurde benutzt<BR>
 [$ endif $]

Dieses Beispiel sendet einen der zwei Sätze zum Browser, in Abhänigkeit davon,
ob die GET-Methode benutzt wurde, um dieses Dokument abzurufen.

=item B<while>, B<endwhile>

Führt eine Schleife aus, bis B<Arg> des B<while> Befehls I<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.

B<HINWEIS>: '&lt;' wird zu '<' bevor es vom Perlinterpreter ausgeführt wird,
außer L<optRawInput> ist gesetzt.

=item B<do>, B<until>

Führt eine Schleife aus, bis B<Arg> des B<until> Befehls I<wahr> ist.

Beispiel:

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

=item B<foreach>, B<endforeach>

Führt eine Schleife aus, für jedes Element des Array, welches als zweites
in B<Arg> steht, wobei die Variable, die als erstes in B<Arg> angegeben ist,
auf den entsprechenden Wert gesetzt wird.

Beispiel:

 [- @arr = (1, 3, 5) -]
 [$ foreach $v @arr $]
     [+ $v +] <BR>
 [$ endforeach $]


=item B<next>

Hat die selbe Funktion wie das Perl next statement. Es kann auch folgende
Syntax benutzt werden, wodurch eine zusätzliche Bedingung (oder anderer Perlcode)
eingefügt werden kann:

    [* next if ($foo) *]

=item B<last>

Hat die selbe Funktion wie das Perl last Statement. Es kann auch folgende
Syntax benutzt werden, wodurch eine zusätzliche Bedingung (oder anderer Perlcode)
eingefügt werden kann:

    [* last if ($foo) *]


=item B<redo>

Hat die selbe Funktion wie das Perl redo statement. Es kann auch folgende
Syntax benutzt werden, wodurch eine zusätzliche Bedingung (oder anderer Perlcode)
eingefügt werden kann:

    [* redo if ($foo) *]


=item B<hidden>

B<Arg> gibt keinen, einen oder zwei Hashs an (mit oder ohne
führendes '%' Zeichen) und ein optionales Array als dritten Parameter.
C<hidden> erzeugt versteckte Eingabefelder für alle Werte, die im ersten Hash,
jedoch nicht im zweiten Hash, enthalten sind. Default ist
C<%fdat> und C<%idat>. Wenn der dritte Parameter angegeben ist, gibt er die
Reihenfolge der Felder an. Default ist C<@ffld>.
Wenn Sie keine Parameter angeben, erzeugt I<Embperl> für alle Werte, die
an dieses Dokument geschickt wurden (in C<%fdat> stehen), verstecke
Eingabefelder, soweit dafür nicht schon andere Eingabefelder existieren.
Dies ist nützlich, um Werte zwischen mehreren Formularen zu transportieren.


Beispiel: (siehe auch eg/x/input.htm aus der Embperl Distribution)

    <FORM ACTION="inhalt.htm" METHOD="GET">
	<INPUT TYPE="TEXT" NAME="field1">
    [$ hidden $]
    </FORM>

Wenn Sie dieses Dokument mit 
    
    https://host/doc.htm?field1=A&field2=B&field3=C

aufrufen, erzeugt I<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>



=item B<var>

Das C<var> Meta-Command definert eine oder mehrere Variablen zur Benutzung
innerhalb dieser Embperlseite und setzt das 
B<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) ;

B<HINWEIS>: 'use strict' innerhalb eines I<Embperl> Dokuments gilt nur innerhalb des Blockes, 
in dem es erscheint.


=item B<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 L<Embperl::Execute> Funktion.

  [- Execute ('#foo')           # Kurzform -]
  [- Execute ({ sub => 'foo'})  # Langform -]

Der Unterschied ist, das I<Embperl> nach dem Aufruf einer Embperl-Funktion
mittels C<Execute>, die internen Zustände (Optionen, Debugflags etc.) 
wieder auf die Werte vor dem Aufruf zurücksetzt. Außerdem ist es möglich
mittels C<Execute> rekursive Funktionsaufrufe zu implementieren.

Es ist ebenfalls möglich Parameter an eine Embperl-Funktion zu übergeben:

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

  
  [- foo ('value') -]


Wenn Sie eine Reihe von oft benötigten Funktionen haben, können Sie sie in
einer I<Embperl> Datei definieren und in Ihre Dokumente importieren:

  [- Execute ({ inputfile => 'mylib.htm', import => 1 }) -]

Dies importiert alle Embperl-Funktionen, die in der Datei F<mylib.htm> 
definiert sind, in die aktuelle Seite, wo sie dann als normale Perlfunktionen
aufgerufen werden können.


=back

=head2 HTML Tags

I<Embperl> behandelt die folgenden HTML Tags speziell.

=over 4

=item B<TABLE>, B</TABLE>, B<TR>, B</TR>

I<Embperl> kann dynamische Tabellen erzeugen (ein- oder zweidimensional). Dazu
ist es lediglich nötig, eine Zeile oder Spalte anzugeben, I<Embperl> expandiert
die Tabelle so weit wie nötig.
Dies geschieht durch die Benutzung der "magischen" Variablen C<$row>, C<$col>
oder C<$cnt>. Solange Sie nicht eine der drei Variablen innerhalb einer Tabelle
benützen, läßt I<Embperl> die Tabelle unverändert.

I<Embperl> überprüft ob C<$row>, C<$col> oder C<$cnt> benutzt werden und wiederholt
allen Text zwischen <TABLE> und </TABLE>, solange der Block in dem
C<$row> oder C<$cnt> enthalten sind, ein Ergebnis ungleich I<undef> zurück gibt.
Aller Text zwischen <TR> und </TR> wird wiederholt, wenn die Variable C<$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 L<$tabmode> (siehe unten) kann das Tabellenendekriterium variiert werden.

Beispiel: (siehe eg/x/table.htm in der Embperl Distribution für weitere Beispiele)

 [- @k = keys %ENV -]
 <TABLE>
     <TR>
         <TD>[+ $i=$row +]</TD>
         <TD>[+ $k[$row] +]</TD>
         <TD>[+ $ENV{$k[$i]} +]</TD>
     </TR> 
 </TABLE>


Der obige Code zeigt alle Elemente des Array C<@k> (das die Schlüssel von 
C<%ENV> enthält) an, so dass alle Umgebungsvariablen (wie im Beispiel
zu I<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.


=item B<TH>, B</TH>

Das <TH> Tag wird als Tabellenüberschrift interpretiert. Wenn die ganze 
Zeile aus <TH> und </TH>, statt aus <TD> und </TD> besteht, werden die
Zellen als Spaltenüberschriften interpretiert und nur einmal ausgegeben.

=item B<DIR>, B<MENU>, B<OL>, B<UL>, B<DL>, B<SELECT>, B</DIR>, B</MENU>,
B</OL>, B</UL>, B</DL>, B</SELECT>

Listen, Menüs und Listboxen werden genau wie eindimensionale Tabellen
behandelt. Nur L<"$row">, L<"$maxrow">, L<"$col">, L<"$maxcol"> und L<"$tabmode">
werden beachtet, L<$col> und L<$maxcol> werden ignoriert.  Siehe auch
F<eg/x/lists.htm> aus der I<Embperl> Distribution für ein Beispiel.

=item B<OPTION>

I<Embperl> prüft ob ein Wert für die entsprechende Option in den
Formulardaten (C<%fdat>) vorhanden ist. Wenn ja wird die
Option als I<ausgewählt> angezeigt.

Beispiel:

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

      Wenn Sie dieses Dokument mit list.htm?SEL1=x aufrufen,
      können Sie die Option bestimmen, die angewählt erscheint.

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


=item B<INPUT>

Das C<INPUT> Tag arbeitet mit den Hashs C<%idat> und C<%fdat> zusammen.
Wenn das C<INPUT> Tag kein C<VALUE> Attribute hat, jedoch in C<%fdat> ein
Element, das dem C<NAME> Attribute entspricht, existiert, erzeugt I<Embperl>
ein C<VALUE> Attribute mit dem Wert aus C<%fdat>.
Alle Werte der C<INPUT> Tags werden in dem Hash C<%idat>, mit dem Namen 
des C<INPUT> Tags als Schlüssel und ihrem Wert, gespeichert.
Für Radiobuttons und Checkboxen (C<TYPE=RADIO> und C<TYPE=CHECKBOX>), wird
das C<CHECKED> Attribute eingefügt, wenn der Wert des C<VALUE> Attributes
mit dem Wert in C<%fdat> übereinstimmt, andernfalls wird C<CHECKED>
entfernt.

Das bedeutet, wenn Sie die Formulardaten an das Dokument selbst schicken
(die URL des C<ACTION> Attributes entspricht dem aktuellen  Dokument
oder fehlt ganz), zeigen alle C<INPUT> Tags automatisch die selben 
Werte an, die der Benutzer vor dem Absenden eingegeben hat.


=item B<TEXTAREA>, B</TEXTAREA>

Das C<TEXTAREA> Tag wird genau wie ein normales C<INPUT> Tag behandelt (siehe oben)


=item B<META HTTP-EQUIV= ...>

C<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 C<META HTTP-EQUIV> und HTTP Header unterschiedlich
ist.

Dies kann ebenfalls benutzt werden, um beliebige HTTP Header zu setzen.
Unter I<mod_perl> können HTTP Header auch mit der Funktion C<header_out>
gesetzt werden.

Beispiel:

    <META HTTP-EQUIV="Language" CONTENT="DE">

Das entspricht der Apachefunktion:

    [- $req_rec ->  header_out("Language" => "DE"); -]

=item B<A>, B<EMBED>, B<IMG>, B<IFRAME>, B<FRAME>, B<LAYER>

Die Ausgaben von Perlblöcken innerhalb des C<HREF> Attributes des C<A> Tags und des
C<SRC> Attributes der anderen Tags werden URL Kodiert, statt HTML Kodiert.
(siehe auch L<$escmode>). Des weiteren expandiert I<Embperl> Array- und Hashreferenzen
innerhalb solcher URLs zur URL Parametersyntax. Beispiel:

  [-
  $A = {A => 1, B => 2} ;  # Hashreference
  @A = (X, 9, Y, 8, Z, 7)
  -]

  <A HREF="https://localhost/tests?[+ $A  +]">
  <A HREF="https://localhost/tests?[+ \@A +]">

wird von I<Embperl> zu Folgendem expandiert:

  <A HREF="https://localhost/tests?A=1&B=2">
  <A HREF="https://localhost/tests?X=9&Y=8&Z=7">


=back


=head1 Gültigkeitsbereiche von Variablen und Cleanup


Der Gültigkeitsbereich von Variablen, die mit C<my> oder C<local>
deklariert wurden, endet am Ende des umschließenden C<[+/- ... -/+]>
Blocks. Der C<[+/- ... -/+]> Block verhält sich in dieser hinsicht
wie Perls C<{ ... }>.

Globale Variablen (alles was nicht mittels C<my> oder C<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 I<Embperl>
eindeutig vergeben, kann aber mittels L<EMBPERL_PACKAGE> explizit
angegeben werden.

Da CGI Skripte sowieso immer als eigenständiger Prozeß ausgeführt werden,
ist ein Cleanup bei CGI Skripten nicht nötig.

Sollen Variablen nicht am Ende des Request aufgeräumt werden, müssen sie
entweder im Hash C<%CLEANUP> (mit Wert 0) eingetragen sein oder innerhalb eines anderen
Packages (z.B. C<$Persistent::handle>) deklariert werden.

Wenn Sie das C<strict> Pragma (C<use strict>) nutzen wollen, können sie
Ihre Variablen mittels des C<var> Meta-Commands deklarieren.

B<HINWEIS:> Da I<Apache::DBI>, wie jedes andere Perlmodul, seinen eigenen
Namensraum hat, funktioniert es ohne Problem zusammen mit I<Embperl>.

Das automatische Cleanup kann mittels L<EMBPERL_OPTIONS> bzw. dem
L<cleanup> Parameter der L<Execute> Funktion abgeschaltet werden.

Ausnahmen für Variablen, die B<nicht> oder zusätzlich aufgeräumt werden sollen, können
mittels des Hash L<%CLEANUP> angegeben werden.

Es ist ebenfalls möglich eine Funktion aufrufen zulassen, wenn I<Embperl>
sein Cleanup durchführt. Soweit definiert, wird die Funktion B<CLEANUP>
aufgerufen, direkt bevor die weiteren Variablen aufgeräumt werden.

 Beispiel:

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


=head1 Vordefinierte Variablen

I<Embperl> hat einige spezielle Variablen mit einer vorgegebenen Bedeutung.


=head2 %ENV

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

=head2 $epreq

Enthält eine Referenz auf das Embperl Request Object. Dies ist dasselbe
wie wenn man C<$epreq = shift> am Seitenanfang schreibt.

=head2 $epapp

Enthält eine Referenz auf das Embperl Application Object. Dies ist dasselbe
wie C<$epreq -> app> zurückliefert.

=head2 %fdat

Enthält alle Formulardaten, die an das Dokument gesendet wurden.
Das C<NAME> Attribute bildet den Schlüssel und das C<VALUE>
Attribute den Wert des Hashelements. Dabei ist es egal, ob die Daten mittels
C<GET> oder C<POST> übetragen wurden. Existieren mehrere Werte mit dem selben Namen,
werden diese mittels C<TAB> getrennt. Diese können z.B. mittels folgenden Code in
ein Array zerlegt werden:

  @array = split (/\t/, $fdat{'fieldname'}) ;

I<Embperl> unterstützt ebenfalls den Kodierungstyp B<multipart/form-data>,
der für Dateiuploads benutzt wird. Das Element in C<%fdat> enthält dann
eine Dateihandle (entsprechend CGI.pm), die benutzt werden kann, um die 
Datei auszulesen.

Dateiupload Beispiel:

HTML Formular:

    <FORM METHOD="POST" ENCTYPE="multipart/form-data">
      <INPUT TYPE="FILE" NAME="ImageName">
    </FORM>

Embperl ACTION:

    [- if (defined $fdat{ImageName}) {
         open FILE, "> /tmp/file.$$";
	 print FILE $buffer
           while read($fdat{ImageName}, $buffer, 32768);
         close FILE;
       }
    -]
	
Wenn I<CGI.pm> 2.46 oder höher installiert ist, ist es weiterhin möglich den
Dateinamen (den B<lokalen> Dateinamen, wie er auf seiten des Browsers heißt)
und Informationen, die von der I<CGI.pm> Funktion C<uploadInfo> zur Verfügung 
gestellt werden, zu erhalten. Der Dateiname ist in dem entsprechenden
C<%fdat> Element direkt enthalten. Um auf die B<uploadInfos> zuzugreifen, muß man 
dem Feldnamen einen Bindestrich voranstellen:

Beispiel:

  # ImageName ist der NAME des Feldes. 
  # Er durch den im HTML Code angegeben ersetzt werden.
  Dateiname:     [+ $fdat{ImageName} +] <br>
  Content-Type:  [+ $fdat{-ImageName} -> {'Content-Type'} +] <br>

B<HINWEIS:> Der Zugriff auf die B<Upload-Infos> erfolgte vor 1.2b11 auf andere
Art und Weise, die nicht mehr unterstützt wird.

B<HINWEIS:> Dies funktioniert ebenfalls in die andere Richtung. Bei Inputtags deren
Name einem %fdat Schlüssel entspricht und die kein Value Attribute haben wird
automatisch der Wert aus %fdat als Value eingesetzt. Siehe L<"HTML Tags"> C<INPUT/OPTION/TEXTAREA>. 

=head2 @ffld

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

=head2 %idat

Enthält alle Werte von allen C<INPUT>, C<TEXTAREA> und C<SELECT/OPTION> Tags,
die in der Seite vorangehen.

=head2 %udat (ab 1.2b1)

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

=head2 %mdat (ab 1.2b2)

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

=head2 $row, $col

Reihen und Spaltenzähler für dynamische Tabellen.
(Siehe L<"HTML Table Tag"|"HTML Tags">.)

=head2 $maxrow, $maxcol

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

=head2 $cnt

Enthält die Anzahl der Tabellenzellen, die bis jetzt angezeigt wurden.
(Siehe L<"HTML Table Tag"|"HTML Tags">.)

=head2 $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:

=over 4

=item $tabmode = 1

Ende, wenn B<ein> Block der C<$row> enthält, C<undef> als Ergebnis hat.
Die Reihe, die den undefinierten Ausdruck enthält, wird B<nicht> mehr angezeigt.

=item $tabmode = 2

Ende, wenn B<ein> Block der C<$row> enthält, C<undef> als Ergebnis hat.
Die Reihe, die den undefinierten Ausdruck enthält, B<wird> angezeigt.

=item $tabmode = 4

Ende, wenn C<$maxrow> Reihen angezeigt wurden.

=back

B<Spaltenende:>

=over 4

=item $tabmode = 16

Ende, wenn B<ein> Block der C<$col> enthält, C<undef> als Ergebnis hat.
Die Spalte, die den undefinierten Ausdruck enthält, wird B<nicht> mehr angezeigt.

=item $tabmode = 32

Ende, wenn B<ein> Block der C<$col> enthält, C<undef> als Ergebnis hat.
Die Spalte, die den undefinierten Ausdruck enthält, B<wird> angezeigt.

=item $tabmode = 64

Ende, wenn C<$maxcol> Spalten angezeigt wurden.

=back

Der Defaultwert von B<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.

=head2 $escmode

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

B<Hinweis:> Normalerweise kann die Kodierung durch Voranstellen eines Backslashes ('\')
vor das entsprechende Zeichen verhindert werden. Das ist recht nützlich, ist aber
in Situation, wo eine Benutzereingabe nochmal angezeigt wird, sehr gefährlich, da dies
dem Benuter ermöglich beliebiges HTML einzugeben. Um dies zu verhindern muß zu den
unten aufgeführten Werten jeweils eine 4 addiert werden. Dies führt dazu, dass I<Embperl>
den Backslash bei der Ausgabe nicht gesondert behandelt. (ab 1.3b4)

B<Hinweis 2:>Um binäre Daten auszugeben muß escmode auf Null gesetzt werden (ab 1.3b6)

=over 4

=item B<$escmode = 8 (oder 15)> (2.0b4 und höher)

Das Resultat von Perlausdrücken wird immer XML Kodiert 
(z.B. '>' wird zu '&gt;' und ' zu &apos;).

=item $escmode = 3 (oder 7)

Das Resultat von Perlausdrücken wird HTML Kodiert (z.B. '>' wird zu '&gt;')
und URL Kodiert ('&' wird zu '%26') innerhalb von C<A>, C<EMBED>, C<IMG>, C<IFRAME>, C<FRAME> und C<LAYER> Tags.

=item $escmode = 2 (oder 6)

Das Resultat von Perlausdrücken wird immer URL Kodiert ('&' wird zu '%26').

=item $escmode = 1 (oder 5)

Das Resultat von Perlausdrücken wird immer HTML Kodiert (z.B. '>' wird zu '&gt;').

=item $escmode = 0

Keine HTML oder URL Kodierung findet statt.

=back

=head2 $req_rec

Diese Variable ist nur vorhanden, wenn I<Embperl> unter I<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 B<perldoc Apache> für weitere Informationen)

=head2 LOG

Dies ist die Dateihandle der I<Embperl> Logdatei. Durch schreiben auf
diese Dateihandle ist es möglich, Zeilen in die I<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, 'Embperl::Log';


=head2 OUT

Diese Dateihandle ist an den I<Embperl> Ausgabestrom gebunden. Ausgaben an diese Handle
haben den selben Effekt wie ein C<[+ ... +]> Block.
(Siehe auch L<optRedirectStdout|"EMBPERL_OPTIONS">)

=head2 @param

Wird durch den C<param> Parameter der C<Execute> Funktion gesetzt. Kann genutzt werden,
um Parameter an ein I<Embperl> Dokument zuübergeben oder zurückzugegben.
(siehe L<Execute|"By calling Embperl::Execut">)

=head2 %http_headers_out (ab 1.2b10)

Dieser Hash ermöglicht es HTTP Header anzugeben, die I<Embperl> vor dem Dokument senden soll.

Ist ein "Location" Header angegeben, setzt I<Embperl> den Status automatisch auf 301. Beispiel:

  [- $http_headers_out{'Location'} = "https://www.actevy.io/embperl/" -]

Wird ein Array als Location angeben, gibt das zweite Element den Status Code an:

  [- $http_headers_out{Location} = [ "https://www.actevy.io/embperl/", 303 ]; -]


Ab 1.3.2 können alle HTTP Header (außer "Content-Type") auch 
mehrere Werte erhalten. Um z.B. mehrere Cookie zu setzen, kann man folgendes schreiben:


  [- $http_headers_out{'Set-Cookie'} = 
      ['name=cook1;value=2;','name=cook2;value=b'] ; -]

Für "Location" und "Content-Type" wird nur der erste Wert berücksichtigt. Leere
Arrays werden ignoriert. Z.B. führt Folgendes B<nicht> zu einem Redirect:

  [- $http_headers_out{'Location'} = [] ; -]




siehe auch L<META HTTP-EQUIV= ...>

=head2 $optXXX $dbgXXX

Alle Optionen (see L<"EMBPERL_OPTIONS">) und alle Debugflags (siehe L<"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:

=over 4

=item $optDisableVarCleanup 

=item $optSafeNamespace     

=item $optOpcodeMask        

=item $optDisableChdir      

=item $optEarlyHttpHeader   

=item $optDisableFormData   

=item $optAllFormData       

=item $optRedirectStdout    

=item $optAllowZeroFilesize 

=item $optKeepSrcInMemory   

=back


=head2 %CLEANUP

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

=head2 %CLEANUPFILE (ab 1.2b6)

Hat die selbe Aufgabe wie C<%CLEANUP>, jedoch können hier Dateinamen hinzugefügt werden und
alle Variable die in diesen Dateien definiert wurden, werden am jedes des entsprechenden
Requests aufgeräumt.


=head1 Session Handling (ab 1.2b2)

I<Embperl> ist in der Lage, Daten pro Benutzer für Sie zu verwalten. Sobald
Sie Daten in den Hash C<%udat> schreiben, sorgt I<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 C<%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 C<%udat> und C<%mdat> bei entsprechender Konfiguration, auch über Prozeß-
oder sogar Rechnergrenzen hinweg möglich. I<Embperl> bedient sich dazu
des Perlmodules I<Apache::Session>.

Ab 1.3.4 verwendet I<Embperl> I<Apache::SessionX> für das Sessing handling.
Dadurch ist keine weitere Konfiguration mehr nötig. Wenn Sie das alte 
Sessionhandling (ohne I<Apache::SessionX>) beibehalten wollen, müssen
Sie 

    PerlSetEnv EMBPERL_SESSION_HANDLER_CLASS Embperl::Session

in Ihrer httpd.conf eintragen und folgende Parameter konfigurieren. Sie
können die folgenden Parameter auch zum überschreiben der 
Standardkonfiguration von I<Apache::SessionX> benutzen.

Um das Session Management zu aktivieren muß I<Apache::Session> (Version 1.53
oder höher) installiert sein. Außerdem müssen Sie I<Embperl>, via 
C<EMBPERL_SESSION_CLASSES>, mitteilen, welcher
Speicher- und Lockingmechanismus genutzt werden soll, ggf. müssen Sie
auch weitere Argumente für I<Apache::Session> setzen.
Um z.B. eine MySQL Datenbank zur Speicherung der Sessions zu benutzen, könnte
die Datei F<startup.pl> folgendermaßen aussehen:

 BEGIN
    {
    $ENV{EMBPERL_SESSION_CLASSES} = "MySQL Semaphore" ;
    $ENV{EMBPERL_SESSION_ARGS}    = "DataSource=dbi:mysql:session UserName=test" ;
    } ;
 use Embperl ;


Dass selbe kann stattdessen auch direkt in die F<httpd.conf> eingetragen werden:

 PerlSetEnv EMBPERL_SESSION_CLASSES "MySQL Semaphore"
 PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=test"
 PerlModule Embperl ;


Konsultieren Sie die Dokumentation von I<Apache::Session> (in diesem Fall
I<Apache::Session::Store::MySQL>) für Informationen wie die Datenbanktabellen
dazu aussehen müssen.

C<EMBPERL_SESSION_ARGS> ist eine Leerzeichen separierte Liste von Name/Wert Paaren
die zusätzlich Parameter für die I<Apache::Session> Klassen angeben können.

Hier ist ein weiteres Beispiel für die Speicherung der Sessiondaten im Dataisystem:

PerlSetEnv EMBPERL_SESSION_CLASSES "File Semaphore"
PerlSetEnv EMBPERL_SESSION_ARGS "Directory=/path/to/your/sessions"

Konsultieren Sie die Dokumentation von I<Apache::Session> um zu erfahren welche
weiteren Speichermöglichkeiten es gibt.

Zusätzlich (optional) zur zur Speicher- und Lockingklasse können in C<EMBPERL_SESSION_CLASSES>
zwei weitere Klassen angegeben werden. Die erste ist für die Serialisierung der Daten zuständig
(Default: C<Storable>) und die zweite für sas erzeugen der ID
(Default: C<MD5>).


B<HINWEIS:> Die obige Konfiguration funktioniert nur mit I<Apache::Session> 1.52 und 
I<Embperl> 1.3b5 oder
höher. Ältere Konfigurationen mit I<Apache::Session> werden weiterhin unterstützt,
Ältere Versionen von Embperl unterstützen nur I<Apache::Session> 1.0x, welches
eine andere Konfiguartion von C<$ENV{EMBPERL_SESSION_CLASSES}> erfordert
(z.B. C<$ENV{EMBPERL_SESSION_CLASSES} = "DBIStore SysVSemaphoreLocker" ; >).



Damit ist das Session Handling eingerichtet und der Benutzung der
Hashs C<%udat> und C<%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 I<Embperl> bzw. I<Apache::Session>
eine Session ID. Für Benutzerbezogene Session wird diese Id mittels eines
Cookies zum Browser gesandt. Außerdem veranlasst I<Embperl> I<Apache::Session>
die Daten zu speichern. Empfängt I<Embperl> einen solchen Cookie mit einer
Id, wird diese zunächst nur abgespeichert, erst bei einem Zugriff auf C<%udat>,
werden die Daten tatsächlich von I<Apache::Session> angefordert. Ebenso
werden die Daten für C<%mdat> erst von I<Apache::Session> angefordert, wenn
auf diesen Hash zugegriffen wird.

=head2 Funktionen/Methoden fürs Session Handling

=head2 Embperl::Req::SetupSession ($req_rec, $Inputfile) [1.3b6+]

Diese Funktion kann von Skripten benutzt werden die in ihrem Verlauf
L<Embperl::Execute|Execute> aufrufen, jedoch vorher schon auf die Sessiondaten
von Embperl zugreifen wollen.

=over 4

=item $req_rec

Apache request record soweit das Skript unter I<mod_perl> läuft, ansonsten C<undef>.

=item $Inputfile

Name der Datei die später von I<Embperl> bearbeitet werden soll. Dient dazu L<%mdat> zu
initialsieren. Wird C<%mdat> nicht benötigt, kann dieser Parameter weggelassen werden.

=back

Liefert eine Referenz auf L<%udat> oder, wenn es in einem Arraykontext aufgerufen wird,
eine Referenz auf L<%udat> und L<%mdat> zurück. Siehe auch C<CleanupSession>.

=head2 Embperl::Req::GetSession / $r -> GetSession [1.3b6+]

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

=head2 Embperl::Req::CleanupSession / $r -> CleanupSession [1.3b6+]

Muß am Ende B<jedes> Skripts aufgerufen werden, welches C<SetupSession> benutzt, danach aber nicht
L<Embperl::Execute|Execute> aufruft.
Wenn es als eine Methode aufgerufen wird muß C<$r> ein C<Embperl::Req> Objekt sein.
Dieses wird als erster Parameter in @_ an jede Seite übergeben.

=head2 Embperl::Req::DeleteSession / $r -> DeleteSession [1.3b6+]

Löscht die Sessiondaten und entfernt den Cookie vom Browser.
Wenn es als eine Methode aufgerufen wird muß C<$r> ein C<Embperl::Req> Objekt sein.
Dieses wird als erster Parameter in @_ an jede Seite übergeben.

=head2 Embperl::Req::RefreshSession / $r -> RefreshSession [1.3b6+]

Stößt das nochmalige senden des Cookies an. Normalerweise wird der Cookie nur beim ersten
Mal gesendet.
Wenn es als eine Methode aufgerufen wird muß C<$r> ein C<Embperl::Req> Objekt sein.
Dieses wird als erster Parameter in @_ an jede Seite übergeben.

=head2 Embperl::Req::SetSessionCookie / $r -> SetSessionCookie [1.3b7+]

Muß von Skripts aufgerufen werden, welches C<SetupSession> benutzen, danach aber nicht
L<Embperl::Execute|Execute> aufrufen, um den Cookie für sie Session-Id zu setzen.
Dies wird normalerweise durch L<Embperl::Execute|Execute> erledigt.
Wenn es als eine Methode aufgerufen wird muß C<$r> ein C<Embperl::Req> Objekt sein.
Dieses wird als erster Parameter in @_ an jede Seite übergeben.


=head1 (Sichere-)Namensräume und Opcode Restriktionen


Da die meisten Web Server mehr als ein Dokument verwalten, ist es nötig,
die Dokumente gegeneinander zu schützen. I<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 L<EMBPERL_PACKAGE> ist es möglich
einen expliziten Packagenamen für ein oder mehere Dokumente vorzugeben.
Dies alles verhindert aber nicht, das durch die Angabe eines Variablennamen
incl. Packagenamen eine Embperlseite auf andere Namensräume zugreifen kann.


Manchmal, z.B. wenn mehrere Personnen Zugriff auf die Webserverinhalte
haben sollen, ist es notwendig Dokumente tatsächlich gegenseitig zuschützen.
Für solche Fällen kann I<Embperl> I<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 I<Safe.pm>)


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

B<HINWEIS:> Für das ausgeführte Dokument erscheint es so, als würde
der Code im Package B<main> ausgeführt!

Eine weitere Möglichkeit, um I<Embperl> Seiten sicher zu machen, ist die
Benutzung von Opcode Restriktionen. Dazu ist es nötig, zuerst ein
B<Safe Compartment> zu erstellen:


 B<$cp = 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 L<optOpcodeMask> in
L<EMBPERL_OPTIONS> setzen
und spezifizieren aus welchem Compartment die Opcode Maske (durch setzen von
L<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 Embperl
    Options ExecCGI
    PerlSetEnv EMBPERL_OPTIONS 12
    PerlSetEnv EMBPERL_COMPARTMENT test
    </Location>

  B<startup.pl:>

    $cp = Embperl::AddCompartment('test');
    $cp->deny(':base_loop');


Beim Starten des Server wird dadurch die Datei F<startup.pl> ausgeführt.
F<startup.pl> erstellt einen Compartment mit Namen
'test', in dem Schleifen gesperrt sind. Alle Seiten die unter
C</embperl/x> liegen, werden nun in einem sicheren Namensraum, mit
gesperrten Schleifen, ausgeführt.

Hinweis: Das Package Name des Compartments wird B<nicht> genutzt!

Mehr Information zum Setzen der Opcode Mask finden Sie in der Dokumentation von Safe.pm und
I<Opcode.pm>.


=head1 Utility Funktionen

=head2 AddCompartment($Name)

Fügt ein Compartment zum Gebrauch mit Embperl hinzu. Embperl nutzt nur
die Opcode Maske und
nicht den Packagenamen des Compartements. C<AddCompartment> gibt den
neu erstellten Compartment zurück, so daß die Methoden zum Freigeben oder
Sperren bestimmter Opcodes aufgerufen werden können.
(siehe auch L<"(Sichere-)Namesräume und Opcode Restriktionen">)

Beispiel:

	$cp = Embperl::AddCompartment('TEST');
	$cp->deny(':base_loop');


=head2 MailFormTo($MailTo, $Subject, $ReturnField)

Sendet den Inhalt des Hashs C<%fdat>, in der durch C<@ffld> angegebenen
Reihenfolge, zur, durch C<$MailTo> angegeben, E-Mail Adresse, mit
C<$Subject> als Betreff. Ist C<$ReturnField> angegeben, wird die in
diesem Feld enthaltene E-Mail Adresse als C<Return-Path> in der
Mail angegeben. C<$ReturnField> sollte normalerweise das Feld angeben
in das der Benutzer seine E-Mail Adresse einträgt.



Wenn Sie nachfolgenden Beispielcode als C<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.

L<"EMBPERL_MAILHOST"> gibt den SMTP Server an den C<MailFormTo> benutzt.
Default ist B<localhost>.

Beispiel:

 <HTML>
 <HEAD>
 <TITLE>Feedback</TITLE>
 </HEAD>
 <BODY>
        [- MailFormTo('webmaster@domain.xy',
		      'Mail von WWW Formular', 'email') -]
	Ihre Daten wurden erfolgreich versandt!
 </BODY>
 </HTML>

Das Beispiel sendet eine Mail mit allen Feldinhalten des Formulars
(das Formular muß als Action die URL des obigen Beispiels angeben)
zu der Mailadresse 'webmaster@domain.xy'. Als Betreff wird
'Mail von WWW Formular' verwendet und der
Return-Path wird auf die Adresse gesetzt, welche im Feld 'email'
eingegeben wurde.

B<HINWEIS:> Sie müssen Net::SMTP (aus dem libnet Package) installiert haben,
wenn Sie diese Funktion nutzen wollen.

=head2 exit

C<exit> überschreibt die standard Perl C<exit> Funktion.
C<exit> beendet die Ausführung des Dokuments und sendet alle bis dahin
ausgeführten Ausgaben zum Browser.

B<Hinweis 1:> exit beendet nur die aktuelle Datei. Wurde die Datei von
einer anderen mittels Execute aufgerufen, wird die aufrufende Datei fortgesetzt.

B<Hinweis 2:> Wird exit mit einem Argument aufgerufen, beendet es den
gesamten Request, nicht nur die Ausführung der aktuellen Datei.

B<Hinweis 3:> Innerhalb eines Perlmoduls, das von einer I<Embperl> Seite
aus aufgerufenen wird, sollten sie C<Apache::exit> verwenden, da das normale
Perl C<exit> ansonsten den kompletten Childprozeß beendet. C<Apache::exit>
führt dazu, dass die Ausführung des Moduls, wie auch der I<Embperl> Seite,
abgebrochen wird, jedoch alle Ausgaben noch zum Browser gelangen.



=head1 Performance

Um die beste Performance von I<Embperl> zu erzielen, ist es notwendig, das Logging auf ein Minimum
zu beschränken. Sie können Embperl drastisch verlangsamen, wenn Sie alle
Logging Option einschalten.
Vorallem sollten Sie B<niemals> L<dbgFlushOutput> oder L<dbgFlushLog>
auf einen Produktionsserver einschalten.
Während der geringfügige Performanceverlust beim Debuggen nicht auffällt, kann
er auf einem stark belasteten Server durchaus ins Gewicht fallen.
Auch die Optionen L<optDisableChdir>, L<optDisableHtmlScan>, L<optDisableCleanup>
haben Auswirkungen auf die Performance.

Lesen Sie ebenfalls B<mod_perl_tuning.pod> für weitere Ideenen zur
Performancesteigerung.



=head1 Bugs

Fehler sind keine bekannt.


=head1 Support

=head2 Rückmeldungen/Anregungen/Probleme/Fehlerreports

Diskussionen zu allen Fragen/Problemen rund um I<Embperl> werden auf
der Embperl Mailingliste (embperl@perl.apache.org) geführt. Sollten Sie Probleme mit
I<Embperl> haben, die sich nach der Lektüre dieser Dokumentation sowie der L<FAQs|"faq_pod">
nicht lösen lassen, ist die Mailingliste der richtige Ort um nachzufragen.
Oft wurden Probleme schon diskutiert, deshalb lohnt sich ein Blick in
die Archive der Liste.

https://mail-archives.apache.org/mod_mbox/perl-embperl

oder in das Archiv der mod_perl Mailingliste für Fragen in Zusammenhang mit mod_perl

https://mail-archives.apache.org/mod_mbox/perl-modperl

Um die Mailingliste zu abbonieren, senden Sie eine Mail an
embperl-subscribe@perl.apache.org, zum von der Liste gestrichen zu werden
genügt eine Mail an embperl-unsubscribe@perl.apache.org .

Haben Sie eine Website die Embperl benutzt, würde ich mich über eine
Rückmeldung freuen und diese ggf. in die Liste der Sites die Embperl
nutzen aufnehmen.


=head2 Kommerzieller Support

Sie erreichen uns via https://www.actevy.io oder richter at embperl dot org


=head1 Links und Download

=head2 Informationen

mod_perl                           https://perl.apache.org/

Embperl                            https://perl.apache.org/embperl/

Embperl (deutsch)                  https://www.actevy.io/embperl/de/

DBIx::Recordset	                   https://metacpan.org/author/GRICHTER

Apache Webserver                   https://www.apache.org/

Weitere Apache module              https://perl.apache.org/src/apache-modlist.html

=head2 Download

mod_perl                            https://perl.apache.org/download/index.html

Embperl                             https://www.embperl.org/downloads

DBIx::Recordset	                    https://metacpan.org/author/GRICHTER

Debian packages                     https://www.cse.unsw.edu.au/~gusl/embperl

PPM für ActiveState                 https://theoryx5.uwinnipeg.ca/ppmpackages/


B<Information wie Embperl installiert wird finden sich in> L<INSTALL.pod>.

=head2 CVS

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

=head1 Syntaxmodes für verschiedene Editoren

=head2 Emacs

Von: Erik Arneson [erik@mind.net]

Man braucht mmm.el von
https://mmm-mode.sourceforge.net/

Anschließend muß man mein mmm-embperl.el downloaden von
https://www.aarg.net/erik/mmm-embperl.el

Dokumentation ist in den Dateien enthalten.

=head2 VIM

Vim Syntaxfile für Vim 5.x & 6.x von Lukas Zapletal mit syntax highliting für JavaScript, VBScript,
Perl+Embperl, CSS und HTML, gelbem Hintergrund für Perl code (wie M$ Interdev) und
funktionierendem Perl folding:
https://vim.sourceforge.net/script.php?script_id=61 

Vim Syntaxfile von Steve Willer: https://www.interlog.com/~willer/embperl.vim

Vim Syntaxfile von Kee Hinckley: https://www.somewhere.com/software/

=head2 Dreamweaver

Dreamweaverextention welche Dreamweaver veranlasst den Embperl code in Ruhe zu lassen
befindet sich unter https://www.somewhere.com/software/


=head1 Author

G. Richter (richter at embperl dot org)