You are viewing a plain text version of this content. The canonical link for it is here.
Posted to modperl-cvs@perl.apache.org by ri...@locus.apache.org on 2000/02/20 21:29:35 UTC
cvs commit: modperl-site/embperl Embperl.pod.1.html Embperl.pod.10.html Embperl.pod.11.html Embperl.pod.12.html Embperl.pod.13.html Embperl.pod.14.html Embperl.pod.15.html Embperl.pod.16.html Embperl.pod.2.html Embperl.pod.3.html Embperl.pod.4.html Embperl.pod.5.html Embperl.pod.6.html Embperl.pod.7.html Embperl.pod.8.html Embperl.pod.9.html Embperl.pod.cont.html Faq.pod.2.html Faq.pod.3.html Faq.pod.4.html Faq.pod.5.html Faq.pod.8.html index.html
richter 00/02/20 12:29:35
Modified: embperl Embperl.pod.1.html Embperl.pod.10.html
Embperl.pod.11.html Embperl.pod.12.html
Embperl.pod.13.html Embperl.pod.14.html
Embperl.pod.15.html Embperl.pod.16.html
Embperl.pod.2.html Embperl.pod.3.html
Embperl.pod.4.html Embperl.pod.5.html
Embperl.pod.6.html Embperl.pod.7.html
Embperl.pod.8.html Embperl.pod.9.html
Embperl.pod.cont.html Faq.pod.2.html Faq.pod.3.html
Faq.pod.4.html Faq.pod.5.html Faq.pod.8.html
index.html
Log:
Embperl Webpages - Changes
Revision Changes Path
1.15 +4 -463 modperl-site/embperl/Embperl.pod.1.html
Index: Embperl.pod.1.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.1.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- Embperl.pod.1.html 2000/02/11 22:34:16 1.14
+++ Embperl.pod.1.html 2000/02/20 20:29:32 1.15
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Operating-Modes</TITLE>
+<TITLE>DESCRIPTION</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Operating_Modes">Operating-Modes</a></strong></h1>
+<A NAME="DESCRIPTION">DESCRIPTION</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,467 +16,8 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.cont.html">PREV (Documentation - Content)</a>] [<a href="Embperl.pod.2.html">NEXT (Runtime configuration)</a>] <br> <UL>
-
- <LI><A href="Embperl.pod.1.html#Offline">Offline</A>
- <LI><A href="Embperl.pod.1.html#As_a_CGI_script">As a CGI script</A>
- <LI><A href="Embperl.pod.1.html#From_mod_perl_Apache_httpd_">From mod_perl (Apache httpd)</A>
- <LI><A href="Embperl.pod.1.html#By_calling_HTML_Embperl_Execut">By calling HTML::Embperl::Execute (\%param)</A>
- <LI><A href="Embperl.pod.1.html#Helper_functions_for_Execute">Helper functions for Execute</A>
- <LI><A href="Embperl.pod.1.html#EXAMPLES_for_Execute_">EXAMPLES for Execute:</A>
- </UL>
-<hr>
-<P>
-Embperl can operate in one of four modes:
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Offline">Offline</A></H2>
-<P>
-Converts an HTML file with embedded Perl statements into a standard HTML
-file.
-
-<P>
-<STRONG>embpexec.pl [-o outputfile] [-l logfile] [-d debugflags] htmlfile
-[query_string]</STRONG>
-
-
-
-<P>
-<STRONG>embpexec.bat [-o outputfile] [-l logfile] [-d debugflags] htmlfile
-[query_string]</STRONG>
-
-
-
-<P>
-Use embpexec.pl on Unix systems and embpexec.bat on Win32 systems.
-
-<DL>
-<DT><STRONG><A NAME="item_htmlfile">htmlfile</A></STRONG><DD>
-<P>
-The full pathname of the HTML file which should be processed by Embperl.
-
-<DT><STRONG><A NAME="item_query_string">query_string</A></STRONG><DD>
-<P>
-Optional. Has the same meaning as the environment variable QUERY_STRING
-when invoked as a CGI script. That is, QUERY_STRING contains everything
-following the first ``?'' in a URL. <query_string> should be
-URL-encoded. The default is no query string.
-
-<DT><STRONG><A NAME="item__o">-o outputfile</A></STRONG><DD>
-<P>
-Optional. Gives the filename to which the output is written. The default is
-stdout.
-
-<DT><STRONG><A NAME="item__l">-l logfile</A></STRONG><DD>
-<P>
-Optional. Gives the filename of the logfile. The default is
-/tmp/embperl.log.
-
-<DT><STRONG><A NAME="item__d">-d debugflags</A></STRONG><DD>
-<P>
-Optional. Specifies the level of debugging (what is written to the log
-file). The default is nothing. See <A href="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> for exact values.
-
-</DL>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="As_a_CGI_script">As a CGI script</A></H2>
-<P>
-Instead of a file being sent directly by the web server, the document is
-processed by the CGI script and the result is sent to the client.
-
-<P>
-<STRONG>embpcgi.pl</STRONG>
-
-
-
-<P>
-<STRONG>embpcgi.bat</STRONG>
-
-
-
-<P>
-Use embpcgi.pl on Unix systems and embpcgi.bat on Win32 systems.
-
-<P>
-If <CODE>embpcgi.pl/embpcgi.bat</CODE> is invoked without any parameters and the environment variable <STRONG>PATH_TRANSLATED</STRONG> is set, it runs itself as a CGI script. This means that form data is taken
-either from the environment variable <STRONG>QUERY_STRING</STRONG> or from stdin, depending on whether or not <STRONG>CONTENT_LENGTH</STRONG> is set. (This will be set by the web server depending on whether the
-request method is GET or POST). Input is taken from the file pointed to by <STRONG>PATH_TRANSLATED</STRONG> and the output is send to stdout. The logfile is generated at its default
-location, which is configurable via the environment variable <STRONG>EMBPERL_LOG</STRONG>.
-
-<P>
-To use this mode you must copy <STRONG>embpcgi.pl</STRONG> to your cgi-bin directory. You can invoke it with the URL <A
-HREF="http://www.domain.xyz/cgi-bin/embpcgi.pl/url/of/your/document.">http://www.domain.xyz/cgi-bin/embpcgi.pl/url/of/your/document.</A>
-
-
-<P>
-The /url/of/your/document will be passed to Embperl by the web server.
-Normal processing (aliasing, etc.) takes place before the URI makes it to
-PATH_TRANSLATED.
-
-<P>
-If you are running the Apache httpd, you can also define
-<STRONG>embpcgi.pl</STRONG> as a handler for a specific file extention or directory.
-
-<P>
-Example of Apache <CODE>srm.conf</CODE>:
-
-<P>
-<PRE> <Directory /path/to/your/html/docs>
- Action text/html /cgi-bin/embperl/embpcgi.pl
- </Directory>
-</PRE>
-<P>
-<STRONG>NOTE 1</STRONG>: Out of security reasons, embpexec.pl must not be used anymore as CGI
-script!
-
-<P>
-<STRONG>NOTE 2</STRONG>: CGI Scripts are not so secure. You should consider using <EM>EMBPERL_ALLOW</EM>
-to restrict the access to the rights documents.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="From_mod_perl_Apache_httpd_">From mod_perl (Apache httpd)</A></H2>
-<P>
-This works like the CGI-Script, but with the advantage that the script is
-compiled only once at server startup, where other one-time actions (such as
-opening files and databases) can take place. This will drastically reduce
-response times for the request. To use this you must compile <CODE>Apache httpd</CODE> with <CODE>mod_perl</CODE> and add <CODE>HTML::Embperl</CODE>
-as the <CODE>PerlHandler</CODE>.
-
-<P>
-Example of Apache <CODE>srm.conf</CODE> or <CODE>httpd.conf</CODE>:
-
-<P>
-<PRE> SetEnv EMBPERL_DEBUG 2285
-</PRE>
-<P>
-<PRE> Alias /embperl /path/to/embperl/eg
-</PRE>
-<P>
-<PRE> <Location /embperl/x>
- SetHandler perl-script
- PerlHandler HTML::Embperl
- Options ExecCGI
- </Location>
-</PRE>
-<P>
-Another possible setup is
-
-<P>
-<PRE> SetEnv EMBPERL_DEBUG 2285
-</PRE>
-<P>
-<PRE> <Files *.epl>
- SetHandler perl-script
- PerlHandler HTML::Embperl
- Options ExecCGI
- </files>
-</PRE>
-<P>
-<PRE> AddType text/html .epl
-</PRE>
-<P>
-Don't forget the <STRONG>AddType</STRONG>. In this setup, all files ending with .epl are processed by Embperl.
-
-<P>
-See the section <A href="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> (dbgLogLink and EMBPERL_VIRTLOG) to find out how you can configure Embperl
-so you can view the log file with your browser!
-
-<P>
-<STRONG>NOTE</STRONG>: When mod_perl is compiled as loadable module (i.e. with USE_DSO) you
-<STRONG>must not</STRONG> load Embperl at server startup time!
-
-<P>
-<STRONG>See also</STRONG>: <A HREF="EmbperlObject.pod.cont.html">"perldoc EmbperlObject"</A> to see how to setup <EM>Embperl</EM> in a way to create your site out of small overwriteable objects.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="By_calling_HTML_Embperl_Execut">By calling HTML::Embperl::Execute (\%param)</A></H2>
-<P>
-Execute can be used to call Embperl from your own modules/scripts (for
-example from a Apache::Registry or CGI script) or from within another
-Embperl page (only 1.2b1 or higher) to nest multiple Embperl pages (for
-example to store a common header or footer in an different file).
-
-<P>
-There are two forms you can use for calling Execute. A short form which
-only takes an filename and optional additional parameters or a long form
-which takes a hash reference as its argument. This gives it the chance to
-vary the parameters according to the job that should be done.
-
-<P>
-(See <STRONG>eg/x/Excute.pl</STRONG> for more detailed examples)
-
-<P>
-<STRONG>See also</STRONG>: <A HREF="EmbperlObject.pod.cont.html">"perldoc EmbperlObject"</A> to see how to setup <EM>Embperl</EM> in a way to create your site out of small overwriteable objects and <A HREF="Mail.pod.cont.html">"perldoc HTML::Embperl::Mail"</A> how to use <EM>Embperl</EM> to send email.
-
-<P>
-<PRE> Execute($filename, $p1, $p2, $pn) ;
-</PRE>
-<P>
-This will cause Embperl to interpret the file with the name
-<CODE>$filename</CODE> and, if specified, pass any additional parameters in
-the array @param (just like <CODE>@_</CODE> in a perl subroutine). The above example
-could also be written in the long form:
-
-<P>
-<PRE> Execute ({inputfile => $filename,
- param => [$p1, $p2, $pn]}) ;
-</PRE>
-<P>
-The possible items for hash of the long form are:
-
-<DL>
-<DT><STRONG><A NAME="item_inputfile">inputfile</A></STRONG><DD>
-<P>
-The file which should be used as source. If <STRONG>input</STRONG> is also specified, this parameter should be given a unique name to identify
-the source. Every time Embperl sees the same text in <STRONG>inputfile</STRONG>, it assumes that you compiled the same source - that means that Embperl
-uses the same package name as in your last call, and only recompiles the
-code if <STRONG>mtime</STRONG> has changed or is undefined.
-
-<DT><STRONG><A NAME="item_sub">sub</A></STRONG><DD>
-<P>
-Call the Embperl subroutine named by this <CODE>parameter(see</CODE> also <STRONG>"[$ sub $]"</STRONG>). Currently the subroutine must be in the same file or if it's in another
-file, the other file has to be imported first.
-
-<DT><STRONG><A NAME="item_input">input</A></STRONG><DD>
-<P>
-Reference to a string which contains the source. <STRONG>inputfile</STRONG> must also be specified to give a name for the source. The name can be any
-text.
-
-<DT><STRONG><A NAME="item_mtime">mtime</A></STRONG><DD>
-<P>
-Last modification time of member <STRONG>input</STRONG>. If undef the code passed by input is always recompiled, else the code is
-only recompiled if mtime changes.
-
-<DT><STRONG><A NAME="item_outputfile">outputfile</A></STRONG><DD>
-<P>
-File to which the output should be written. If neither outputfile nor
-output is specified, ouput is written to stdout.
-
-<DT><STRONG><A NAME="item_output">output</A></STRONG><DD>
-<P>
-Reference to a scalar where the output should be written to.
-
-<DT><STRONG><A NAME="item_import">import</A></STRONG><DD>
-<P>
-A value of zero tell's Embperl not to execute the page, but define all
-subrountines found inside. This is neccessary before calling them with
-Execute by the <STRONG>sub</STRONG>
-parameter or for an later import.
-
-<P>
-A value of one tell's Embperl to define to subrountines inside the file (if
-not already done) and to import them as perl subroutines into the current
-namespace.
-
-<P>
-See <STRONG>[$ sub $]</STRONG> metacommand and section about subroutines for more infos.
-
-<DT><STRONG><A NAME="item_req_rec">req_rec</A></STRONG><DD>
-<P>
-NOTE: The req_rec parameter isn't necessary anymore in versions >= 1.2b2
-
-<P>
-If used under mod_perl, you should set the req_rec parameter to the Apache
-request record object provided by mod_perl.
-
-<DT><STRONG><A NAME="item_cleanup">cleanup</A></STRONG><DD>
-<P>
-This value specifies if and when the cleanup of the package should be
-executed. (See <A href="Embperl.pod.4.html#Variable_scope_and_cleanup">Variable scope and cleanup</A> below for more information on cleanup)
-
-<DL>
-<DT><STRONG>cleanup = -1</STRONG><DD>
-<P>
-Never cleanup the variables
-
-<DT><STRONG>cleanup = 0 or not specified</STRONG><DD>
-<P>
-If running under mod_perl, cleanup is delayed until the connection to the
-client is closed, so it does not lengthen the response time to the client.
-If the Execute function is called more the once before the end of the
-request, all cleanups take place after the end of the request and not
-between calls to Execute.
-
-<P>
-If running as a CGI or offline, cleanup takes place immediately.
-
-<DT><STRONG>cleanup = 1</STRONG><DD>
-<P>
-Immediate cleanup
-
-</DL>
-<DT><STRONG><A NAME="item_param">param</A></STRONG><DD>
-<P>
-Can be used to pass parameters to the Embperl document and back. Must
-contain a reference to an array.
-
-<P>
-<PRE> Example:
-</PRE>
-<P>
-<PRE> HTML::Embperl::Execute(..., param => [1, 2, 3]) ;
- HTML::Embperl::Execute(..., param => \@parameters) ;
-</PRE>
-<P>
-The array @param in the Embperl document is setup as an alias to the array. See
-eg/x/Excute.pl for a more detailed example.
-
-<DT><STRONG><A NAME="item_ffld">ffld and fdat</A></STRONG><DD>
-<P>
-Could be used to setup the two Embperl predefined variables.
-
-<DT><STRONG><A NAME="item_firstline">firstline</A></STRONG><DD>
-<P>
-Specifies the first linenumber of the sourcefile (Default: 1)
-
-<DT><STRONG><A NAME="item_options">options</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_OPTIONS">EMBPERL_OPTIONS</A> (see below), except for cleanup.
-
-<P>
-<STRONG>NOTE:</STRONG> You should set the <STRONG>optDisableFormData</STRONG> if you have already read the form data from stdin while in a POST request.
-Otherwise Execute will hang and try to read the data a second time.
-
-<DT><STRONG><A NAME="item_debug">debug</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> (see below).
-
-<DT><STRONG><A NAME="item_escmode">escmode</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_ESCMODE">EMBPERL_ESCMODE</A> (see below).
-
-<DT><STRONG><A NAME="item_package">package</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_PACKAGE">EMBPERL_PACKAGE</A> (see below).
-
-<DT><STRONG><A NAME="item_virtlog">virtlog</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A> (see below). If <STRONG>virtlog</STRONG> is equal to <STRONG>uri</STRONG> the logfile is sent.
-
-<DT><STRONG><A NAME="item_allow">allow (1.2b10 and above)</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_ALLOW_only_1_2b10_and_a">"EMBPERL_ALLOW"</A> (see below)
-
-<DT><STRONG><A NAME="item_path">path (1.3b1 and above)</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_PATH_1_3b1_and_above_">"EMBPERL_PATH"</A> (see below)
-
-<DT><STRONG><A NAME="item_uri">uri</A></STRONG><DD>
-<P>
-The URI of the request. Only needed for the virtlog feature.
-
-<DT><STRONG><A NAME="item_compartment">compartment</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_COMPARTMENT">EMBPERL_COMPARTMENT</A> (see below).
-
-<DT><STRONG><A NAME="item_input_func">input_func</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_INPUT_FUNC">EMBPERL_INPUT_FUNC</A> (see below). Additionaly you can specify an code reference to an perl
-function, which is used as input function or an array reference, where the
-first element contains the code reference and further elements contains
-additional arguments passed to the function.
-
-<DT><STRONG><A NAME="item_output_func">output_func</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_OUTPUT_FUNC">EMBPERL_OUTPUT_FUNC</A> (see below). Additionaly you can specify an code reference to an perl
-function, which is used as output function or an array reference, where the
-first element contains the code reference and further elements contains
-additional arguments passed to the function.
-
-<DT><STRONG><A NAME="item_cookie_name">cookie_name</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_COOKIE_NAME">EMBPERL_COOKIE_NAME</A> (see below).
-
-<DT><STRONG><A NAME="item_cookie_path">cookie_path</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_COOKIE_PATH">EMBPERL_COOKIE_PATH</A> (see below).
-
-<DT><STRONG><A NAME="item_cookie_domain">cookie_domain</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_COOKIE_DOMAIN">EMBPERL_COOKIE_DOMAIN</A> (see below).
-
-<DT><STRONG><A NAME="item_cookie_expires">cookie_expires</A></STRONG><DD>
-<P>
-Same as <A href="Embperl.pod.2.html#EMBPERL_COOKIE_EXPIRES">EMBPERL_COOKIE_EXPIRES</A> (see below).
-
-<DT><STRONG><A NAME="item_errors">errors</A></STRONG><DD>
-<P>
-Takes a reference to an array. Upon return the array will contain a copy of
-all errormessages, as long as there are any.
-
-</DL>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Helper_functions_for_Execute">Helper functions for Execute</A></H2>
-<DL>
-<DT><STRONG><A NAME="item_HTML">HTML::Embperl::Init ($Logfile, $DebugDefault)</A></STRONG><DD>
-<P>
-This function can be used to setup the logfile path and (optional) a
-default value for the debugflags, which will be used in further calls to
-Execute. There will always be only one logfile, but you can use <STRONG>Init</STRONG>
-to change it at any time.
-
-<P>
-<STRONG>NOTE:</STRONG> You do not need to call Init in version >= 0.27. The initialization of
-Embperl takes place automatically when it is loaded.
-
-<DT><STRONG><A NAME="item_HTML">HTML::Embperl::ScanEnvironement (\%params)</A></STRONG><DD>
-<P>
-Scans the <STRONG>%ENV</STRONG> and setups <STRONG>%params</STRONG> for use by <STRONG>Execute</STRONG>. All Embperl runtime configuration options are recognized, except
-EMBPERL_LOG.
-
-</DL>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EXAMPLES_for_Execute_">EXAMPLES for Execute:</A></H2>
-<P>
-<PRE> # Get source from /path/to/your.html and
- # write output to /path/to/output'
-</PRE>
-<P>
-<PRE> HTML::Embperl::Execute ({ inputfile => '/path/to/your.html',
- outputfile => '/path/to/output'}) ;
-</PRE>
-<P>
-<PRE> # Get source from scalar and write output to stdout
- # Don't forget to modify mtime if $src changes
-</PRE>
-<P>
-<PRE> $src = '<html><head><title>Page [+ $no +]</title></head>' ;
-</PRE>
-<P>
-<PRE> HTML::Embperl::Execute ({ inputfile => 'some name',
- input => \$src,
- mtime => 1 }) ;
-</PRE>
-<P>
-<PRE> # Get source from scalar and write output to another scalar
-</PRE>
-<P>
-<PRE> my $src = '<html><head><title>Page [+ $no +]</title></head>' ;
- my $out ;
-</PRE>
-<P>
-<PRE> HTML::Embperl::Execute ({ inputfile => 'another name',
- input => \$src,
- mtime => 1,
- output => \$out }) ;
-</PRE>
-<P>
-<PRE> print $out ;
-</PRE>
-<P>
-<PRE> # Include a common header in an Embperl page,
- # which is stored in /path/to/head.html
-
- [- Execute ('/path/to/head.html') -]
-
-</PRE>
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.cont.html">PREV (Documentation - Content)</a>] [<a href="Embperl.pod.2.html">NEXT (Runtime configuration)</a>] <br>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.cont.html">PREV (Documentation - Content)</a>] [<a href="Embperl.pod.2.html">NEXT (Operating-Modes)</a>] <br><hr>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.cont.html">PREV (Documentation - Content)</a>] [<a href="Embperl.pod.2.html">NEXT (Operating-Modes)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.7 +51 -265 modperl-site/embperl/Embperl.pod.10.html
Index: Embperl.pod.10.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.10.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Embperl.pod.10.html 1999/08/30 04:24:11 1.6
+++ Embperl.pod.10.html 2000/02/20 20:29:32 1.7
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Inside Embperl - How the embedded Perl code is actually processed</TITLE>
+<TITLE>Input/Output Functions</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Inside_Embperl_How_the_embedde">Inside Embperl - How the embedded Perl code is actually processed</a></strong></h1>
+<A NAME="Input_Output_Functions">Input/Output Functions</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,297 +16,83 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.9.html">PREV (Input/Output Functions)</a>] [<a href="Embperl.pod.11.html">NEXT (Performance)</a>] <br> <UL>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.9.html">PREV (Utility Functions)</a>] [<a href="Embperl.pod.11.html">NEXT (Inside Embperl - How the embedded Perl code is actually processed)</a>] <br> <UL>
- <LI><A href="Embperl.pod.10.html#1_Remove_the_HTML_tags_Now_it_">1. Remove the HTML tags. Now it looks like</A>
- <LI><A href="Embperl.pod.10.html#2_Translate_HTML_escapes_to_ASC">2. Translate HTML escapes to ASCII characters</A>
- <LI><A href="Embperl.pod.10.html#3_Remove_all_carriage_returns">3. Remove all carriage returns</A>
- <LI><A href="Embperl.pod.10.html#4_Eval_perl_code_into_a_subrout">4. Eval perl code into a subroutine</A>
- <LI><A href="Embperl.pod.10.html#5_Call_the_subroutine">5. Call the subroutine</A>
- <LI><A href="Embperl.pod.10.html#6_Escape_special_characters_in_">6. Escape special characters in the return value</A>
- <LI><A href="Embperl.pod.10.html#7_Send_the_return_value_as_outp">7. Send the return value as output to the destination</A>
+ <LI><A href="Embperl.pod.10.html#ProxyInput_r_in_mtime_sr">ProxyInput ($r, $in, $mtime, $src, $dest)</A>
+ <LI><A href="Embperl.pod.10.html#LogOutput_r_out_basepath_">LogOutput ($r, $out, $basepath)</A>
</UL>
<hr>
<P>
-If Embperl encounters a piece of Perl code
- <STRONG>([+/-/!/$ .... $/!/-/+])</STRONG>
-it takes the following steps.
-
-<OL>
-<LI><STRONG><A NAME="item_Remove_anything_which_looks_like">Remove anything which looks like an HTML tag</A></STRONG>
-<LI><STRONG><A NAME="item_Translate_HTML_escapes_to_their_">Translate HTML escapes to their corresponding ASCII characters</A></STRONG>
-<LI><STRONG><A NAME="item_Remove_all_carriage_returns">Remove all carriage returns</A></STRONG>
-<LI><STRONG><A NAME="item_Eval_the_Perl_code_into_a_subrou">Eval the Perl code into a subroutine</A></STRONG>
-<LI><STRONG><A NAME="item_Call_the_subroutine">Call the subroutine</A></STRONG>
-<LI><STRONG><A NAME="item_Escape_special_characters_in_the">Escape special characters in the return value</A></STRONG>
-<LI><STRONG><A NAME="item_Send_the_return_value_as_output_">Send the return value as output to the destination (browser or file)</A></STRONG>
-</OL>
-<P>
-Steps 1-4 take place only the first time the Perl code is encountered.
-Embperl stores the eval'ed subroutine, so all subsequent requests only need
-to execute steps 5-7.
-
-<P>
-Steps 6 and 7 take place only for code surrounded by [+ ... +].
-
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="ProxyInput_r_in_mtime_sr">ProxyInput ($r, $in, $mtime, $src, $dest)</A></H2>
<P>
-What does this mean?
-
-<P>
-Let's take a piece of code like the following:
-
-<P>
-<PRE> [+ <BR>
- $a = "This '&gt;' is a greater-than sign"
- <BR> +]
-</PRE>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="1_Remove_the_HTML_tags_Now_it_">1. Remove the HTML tags. Now it looks like</A></H2>
-<P>
-<PRE> [+
- $a = "This '&gt;' is a greater-than sign"
- +]
+<PRE> B<USAGE in srm.conf:>
</PRE>
-<P>
-The <BR>s were inserted by some WYSIWYG HTML editor (e.g., by hitting
-return to make the source more readable. Also, such editors often generate
-``random'' tags like <FONT>, etc.). Embperl removes them so they
-don't cause syntax errors.
-
-<P>
-There are cases where you actually want the HTML tag to be there. For
-example, suppose you want to output something like
-
<P>
-<PRE> [+ "<FONT COLOR=$col>" +]
+<PRE> <Location /embperl/ifunc>
+ SetHandler perl-script
+ PerlHandler HTML::Embperl
+ Options ExecCGI
+ PerlSetEnv EMBPERL_INPUT_FUNC "ProxyInput, /embperl/ifunc, <A HREF="http://otherhost/otherpath"">http://otherhost/otherpath"</A>;
+ </Location>
</PRE>
<P>
-If you write it this way, Embperl will just remove everything, leaving only
+This input function will request the source from another URL instead of
+reading it from the disk. In the above USAGE Example, a request to
+/embperl/ifunc/foo.html, will first fetch the URL <A
+HREF="http://otherhost/otherpath/foo.html,">http://otherhost/otherpath/foo.html,</A>
+and then it will process this document by Embperl and then it will send it
+to the browser.
<P>
-<PRE> [+ "" +]
-</PRE>
-<P>
-There are several ways to handle this correctly.
+This could be used to process documents by mod_include <STRONG>and</STRONG> Embperl, so in one document there can be both Server-Side Includes and
+Embperl Commands.
-<P>
-<PRE> a. <FONT COLOR=[+$col+]>
- Move the HTML tag out of the Perl code. This is the best way, but
- it is not possible every time.
-</PRE>
-<P>
-<PRE> b. [+ "\<FONT COLOR=$col>" +]
- You can escape the opening angle bracket of the tag with `\'.
-</PRE>
-<P>
-<PRE> c. [+ "&lt;FONT COLOR=$col&gt;" +]
-</PRE>
-<P>
-<PRE> You can use the HTML escapes instead of the ASCII characters.
- Most HTML editors will automatically do this. (In this case,
- you don't have to worry about it at all.)
-</PRE>
-<P>
-<PRE> d. Set optRawInput (see below).
- This will completely disable the removal of HTML tags.
-</PRE>
-<P>
-NOTE: In cases b-d, you must also be aware of output escaping (see below).
-
-<P>
-You should also be aware that Embperl will interpret the Perl spaceship
-operator (<>) as an HTML tag and will remove it. So instead of
-
-<P>
-<PRE> [- $line = <STDIN>; -]
-</PRE>
-<P>
-you need to write either
-
-<P>
-<PRE> a. [- $line = \<STDIN>; -]
- b. [- $line = &lt;STDIN&gt;; -]
-</PRE>
-<P>
-Again, if you use a high-level HTML editor, it will probably write version
-(b) for you automatically.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="2_Translate_HTML_escapes_to_ASC">2. Translate HTML escapes to ASCII characters</A></H2>
-<P>
-Since Perl doesn't understand things like <CODE>$a</CODE> &lt; $b,
-Embperl will translate it to <CODE>$a</CODE> < $b. If we take the
-example from earlier, it will now look like
-
-<P>
-<PRE> [+
- $a = "This '>' is a greater sign"
- +]
-</PRE>
-<P>
-This step is done to make it easy to write Perl code in a high-level HTML
-editor. You do not have to worry that your editor is writing &gt;
-instead of > in the source.
-
-<P>
-Again, sometimes you need to have such escapes in your code. You can write
-them
-
-<P>
-<PRE> a. \&gt;
- Escape them with a `\' and Embperl will not translate them.
-</PRE>
<P>
-<PRE> b. &amp;gt;
- Write the first `&' as its HTML escape (&amp;). A normal HTML
- editor will do this on its own if you enter &gt; as text.
+<PRE> Example B<srm.conf> for B<SSI> and B<Embperl>:
</PRE>
<P>
-<PRE> c. Set optRawInput (see below)
- This will completely disable the input translation.
+<PRE> <Location /embperl>
+ SetHandler perl-script
+ PerlHandler HTML::Embperl
+ Options ExecCGI
+ PerlSetEnv EMBPERL_INPUT_FUNC "ProxyInput, /embperl, <A HREF="http://localhost/src"">http://localhost/src"</A>;
+ </Location>
</PRE>
-<P>
-Since not all people like writing in a high level or WYSIWYG HTML editor,
-there is an option to disable steps 1 and 2. You can use the
-<STRONG>optRawInput</STRONG> in EMBPERL_OPTIONS to tell Embperl to leave the Perl code as it is. It is
-highly recommended to set this option if you are writing your HTML in an
-ASCII editor. You normally don't want to set it if you use some sort of
-high level HTML editor.
-
<P>
-You can also set the optRawInput in your document by using <STRONG>$optRawInput</STRONG>, but you must be aware that it does not have any consequences for the
-current block, because the current block is translated before it is
-executed. So write it in separate blocks:
-
-<P>
-<PRE> [- $optRawInput = 1 -]
- [- $line = <FILEHANDLE> -]
+<PRE> <Location /src>
+ SetHandler server-parsed
+ Options +Includes
+ </Location>
</PRE>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="3_Remove_all_carriage_returns">3. Remove all carriage returns</A></H2>
-<P>
-All carriage returns (<STRONG>\r</STRONG>) are removed from the Perl code, so you can write source on a DOS/Windows
-platform and execute it on a UNIX server. (Perl doesn't like getting
-carriage returns in the code it parses.)
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="4_Eval_perl_code_into_a_subrout">4. Eval perl code into a subroutine</A></H2>
-<P>
-The next step generates a subroutine out of your Perl code. In the above
-example it looks like:
-
<P>
-sub foo { <CODE>$a</CODE> = ``This '>' is a greater sign'' }
+The source files must be in the location /src, but they will be requested
+via the URI /embperl. Every request to /embperl/foo.html will do a
+proxy-request to /src/foo.html. The file /src/foo.html will be processed by
+mod_include and then sent to Embperl, where it can be processed by Embperl
+before being sent to the browser. It would be also possible to use two
+httpd's on different ports. In this configuration, the source and the URI
+location could be the same.
<P>
-The subroutine is now stored in the Perl interpreter in its internal
-precompiled format and can be called later as often as necessary without
-doing steps 1-4 again. Embperl recognizes if you request the same document
-a second time and will just call the compiled subroutine. This will also
-speed up the execution of dynamic tables and loops, because the code inside
-must be compiled only on the first iteration.
-
-<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="5_Call_the_subroutine">5. Call the subroutine</A></H2>
-<P>
-Now the subroutine can be called to actually execute the code.
-
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="LogOutput_r_out_basepath_">LogOutput ($r, $out, $basepath)</A></H2>
<P>
-If Embperl isn't executing a [+ ... +] block we are done. If it is a [+ ...
-+] block, Embperl needs to generate output, so it continues.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="6_Escape_special_characters_in_">6. Escape special characters in the return value</A></H2>
-<P>
-Our example returns the string:
-
-<P>
-``This '>' is a greater sign''
-
-<P>
-The greater sign is literal text (and not a closing html tag), so according
-to the HTML specification it must be sent as &gt; to the browser. In
-most cases, this won't be a problem, because the browser will display the
-correct text if we send a literal '>'. Also we could have directly
-written &gt; in our Perl string. But when the string is, for example,
-the result of a database query and/or includes characters from national
-character sets, it's absolutely necessary to send them correctly-escaped to
-the browser to get the desired result.
-
-<P>
-A special case is the <A> HTML tag. Since it includes a URL, the text
-must be URL-escaped instead of HTML-escaped. This means special characters
-like `&' must be sent by their hexadecimal ASCII code and blanks must
-be translated to a `+' sign. If you do not do this, your browser may not be
-able to interpret the URL correctly.
-
-<P>
-Example:
-
-<P>
-<PRE> <A HREF="<A HREF="http://host/script?name=">http://host/script?name=</A>[+$n+]">
+<PRE> B<USAGE in srm.conf:>
</PRE>
-<P>
-When <CODE>$n</CODE> is ``My name'' the requested URL, when you click on
-the hyperlink, will be
-
-<P>
-<PRE> <A HREF="http://host/script?name=My+name">http://host/script?name=My+name</A>
-</PRE>
-<P>
-In some cases it is useful to disable escaping. This can be done by the
-variable <STRONG>$escmode</STRONG>.
-
-<P>
-Example: (For better readability, we assume that optRawInput is set.
-Without it, you need to cover the Embperl pre-processing described in steps
-1-3.)
-
<P>
-<PRE> [+ "<FONT COLOR=5>" +]
+<PRE> <Location /embperl/ofunc>
+ SetHandler perl-script
+ PerlHandler HTML::Embperl
+ Options ExecCGI
+ PerlSetEnv EMBPERL_OUTPUT_FUNC "LogOutput, /usr/msrc/embperl/test/tmp/log.out"
+ </Location>
</PRE>
-<P>
-<PRE> This will be sent to the browser as &lt;FONT COLOR=5&gt;, so you
- will see the tag on the browser screen instead of the browser
- switching the color.
-</PRE>
-<P>
-<PRE> [+ local $escmode=0 ; "<FONT COLOR=5>" +]
-</PRE>
-<P>
-<PRE> This will (locally) turn off escaping and send the text as a plain
- HTML tag to the browser, so the color of the output will change.
-</PRE>
-<P>
-<PRE> NOTE: You cannot set $escmode more than once inside a [+ ... +] block.
- Embperl uses the first setting of $escmode it encounters inside the block.
- If you need to change $escmode more than once, you must use muliple
- [+ ... +] blocks.
-
-</PRE>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="7_Send_the_return_value_as_outp">7. Send the return value as output to the destination
-(browser/file)</A></H2>
-<P>
-Now everything is done and the output can be sent to the browser. If you
-haven't set dbgEarlyHttpHeaders, the output is buffered until the
-successful completion of document execution of the document, and is sent to
-the browser along with the HTTP headers. If an error occurs, an error
-document is sent instead.
-
<P>
-The content length and every <META HTTP-EQUIV=...> is added to the
-HTTP header before it is sent. If Embperl is executed as a subrequest or
-the output is going to a file, no http header is sent.
+LogOutput is a custom output function. It sends the output to the browser <STRONG>and</STRONG>
+writes the output to a unique file. The filename has the the form
+``$basepath.$$.$LogOutputFileno''.
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.9.html">PREV (Input/Output Functions)</a>] [<a href="Embperl.pod.11.html">NEXT (Performance)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.9.html">PREV (Utility Functions)</a>] [<a href="Embperl.pod.11.html">NEXT (Inside Embperl - How the embedded Perl code is actually processed)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.6 +289 -14 modperl-site/embperl/Embperl.pod.11.html
Index: Embperl.pod.11.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.11.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Embperl.pod.11.html 1999/11/04 06:49:30 1.5
+++ Embperl.pod.11.html 2000/02/20 20:29:32 1.6
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Performance</TITLE>
+<TITLE>Inside Embperl - How the embedded Perl code is actually processed</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Performance">Performance</a></strong></h1>
+<A NAME="Inside_Embperl_How_the_embedde">Inside Embperl - How the embedded Perl code is actually processed</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,22 +16,297 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.10.html">PREV (Inside Embperl - How the embedded Perl code is actually processed)</a>] [<a href="Embperl.pod.12.html">NEXT (Bugs)</a>] <br><hr>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.10.html">PREV (Input/Output Functions)</a>] [<a href="Embperl.pod.12.html">NEXT (Performance)</a>] <br> <UL>
+
+ <LI><A href="Embperl.pod.11.html#1_Remove_the_HTML_tags_Now_it_">1. Remove the HTML tags. Now it looks like</A>
+ <LI><A href="Embperl.pod.11.html#2_Translate_HTML_escapes_to_ASC">2. Translate HTML escapes to ASCII characters</A>
+ <LI><A href="Embperl.pod.11.html#3_Remove_all_carriage_returns">3. Remove all carriage returns</A>
+ <LI><A href="Embperl.pod.11.html#4_Eval_perl_code_into_a_subrout">4. Eval perl code into a subroutine</A>
+ <LI><A href="Embperl.pod.11.html#5_Call_the_subroutine">5. Call the subroutine</A>
+ <LI><A href="Embperl.pod.11.html#6_Escape_special_characters_in_">6. Escape special characters in the return value</A>
+ <LI><A href="Embperl.pod.11.html#7_Send_the_return_value_as_outp">7. Send the return value as output to the destination</A>
+ </UL>
+<hr>
+<P>
+If Embperl encounters a piece of Perl code
+ <STRONG>([+/-/!/$ .... $/!/-/+])</STRONG>
+it takes the following steps.
+
+<OL>
+<LI><STRONG><A NAME="item_Remove_anything_which_looks_like">Remove anything which looks like an HTML tag</A></STRONG>
+<LI><STRONG><A NAME="item_Translate_HTML_escapes_to_their_">Translate HTML escapes to their corresponding ASCII characters</A></STRONG>
+<LI><STRONG><A NAME="item_Remove_all_carriage_returns">Remove all carriage returns</A></STRONG>
+<LI><STRONG><A NAME="item_Eval_the_Perl_code_into_a_subrou">Eval the Perl code into a subroutine</A></STRONG>
+<LI><STRONG><A NAME="item_Call_the_subroutine">Call the subroutine</A></STRONG>
+<LI><STRONG><A NAME="item_Escape_special_characters_in_the">Escape special characters in the return value</A></STRONG>
+<LI><STRONG><A NAME="item_Send_the_return_value_as_output_">Send the return value as output to the destination (browser or file)</A></STRONG>
+</OL>
+<P>
+Steps 1-4 take place only the first time the Perl code is encountered.
+Embperl stores the eval'ed subroutine, so all subsequent requests only need
+to execute steps 5-7.
+
+<P>
+Steps 6 and 7 take place only for code surrounded by [+ ... +].
+
+<P>
+What does this mean?
+
+<P>
+Let's take a piece of code like the following:
+
+<P>
+<PRE> [+ <BR>
+ $a = "This '&gt;' is a greater-than sign"
+ <BR> +]
+</PRE>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="1_Remove_the_HTML_tags_Now_it_">1. Remove the HTML tags. Now it looks like</A></H2>
+<P>
+<PRE> [+
+ $a = "This '&gt;' is a greater-than sign"
+ +]
+</PRE>
+<P>
+The <BR>s were inserted by some WYSIWYG HTML editor (e.g., by hitting
+return to make the source more readable. Also, such editors often generate
+``random'' tags like <FONT>, etc.). Embperl removes them so they
+don't cause syntax errors.
+
+<P>
+There are cases where you actually want the HTML tag to be there. For
+example, suppose you want to output something like
+
+<P>
+<PRE> [+ "<FONT COLOR=$col>" +]
+</PRE>
+<P>
+If you write it this way, Embperl will just remove everything, leaving only
+
+<P>
+<PRE> [+ "" +]
+</PRE>
+<P>
+There are several ways to handle this correctly.
+
+<P>
+<PRE> a. <FONT COLOR=[+$col+]>
+ Move the HTML tag out of the Perl code. This is the best way, but
+ it is not possible every time.
+</PRE>
+<P>
+<PRE> b. [+ "\<FONT COLOR=$col>" +]
+ You can escape the opening angle bracket of the tag with `\'.
+</PRE>
+<P>
+<PRE> c. [+ "&lt;FONT COLOR=$col&gt;" +]
+</PRE>
+<P>
+<PRE> You can use the HTML escapes instead of the ASCII characters.
+ Most HTML editors will automatically do this. (In this case,
+ you don't have to worry about it at all.)
+</PRE>
+<P>
+<PRE> d. Set optRawInput (see below).
+ This will completely disable the removal of HTML tags.
+</PRE>
+<P>
+NOTE: In cases b-d, you must also be aware of output escaping (see below).
+
+<P>
+You should also be aware that Embperl will interpret the Perl spaceship
+operator (<>) as an HTML tag and will remove it. So instead of
+
+<P>
+<PRE> [- $line = <STDIN>; -]
+</PRE>
+<P>
+you need to write either
+
+<P>
+<PRE> a. [- $line = \<STDIN>; -]
+ b. [- $line = &lt;STDIN&gt;; -]
+</PRE>
+<P>
+Again, if you use a high-level HTML editor, it will probably write version
+(b) for you automatically.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="2_Translate_HTML_escapes_to_ASC">2. Translate HTML escapes to ASCII characters</A></H2>
+<P>
+Since Perl doesn't understand things like <CODE>$a</CODE> &lt; $b,
+Embperl will translate it to <CODE>$a</CODE> < $b. If we take the
+example from earlier, it will now look like
+
+<P>
+<PRE> [+
+ $a = "This '>' is a greater sign"
+ +]
+</PRE>
+<P>
+This step is done to make it easy to write Perl code in a high-level HTML
+editor. You do not have to worry that your editor is writing &gt;
+instead of > in the source.
+
+<P>
+Again, sometimes you need to have such escapes in your code. You can write
+them
+
+<P>
+<PRE> a. \&gt;
+ Escape them with a `\' and Embperl will not translate them.
+</PRE>
+<P>
+<PRE> b. &amp;gt;
+ Write the first `&' as its HTML escape (&amp;). A normal HTML
+ editor will do this on its own if you enter &gt; as text.
+</PRE>
+<P>
+<PRE> c. Set optRawInput (see below)
+ This will completely disable the input translation.
+</PRE>
+<P>
+Since not all people like writing in a high level or WYSIWYG HTML editor,
+there is an option to disable steps 1 and 2. You can use the
+<STRONG>optRawInput</STRONG> in EMBPERL_OPTIONS to tell Embperl to leave the Perl code as it is. It is
+highly recommended to set this option if you are writing your HTML in an
+ASCII editor. You normally don't want to set it if you use some sort of
+high level HTML editor.
+
+<P>
+You can also set the optRawInput in your document by using <STRONG>$optRawInput</STRONG>, but you must be aware that it does not have any consequences for the
+current block, because the current block is translated before it is
+executed. So write it in separate blocks:
+
+<P>
+<PRE> [- $optRawInput = 1 -]
+ [- $line = <FILEHANDLE> -]
+</PRE>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="3_Remove_all_carriage_returns">3. Remove all carriage returns</A></H2>
+<P>
+All carriage returns (<STRONG>\r</STRONG>) are removed from the Perl code, so you can write source on a DOS/Windows
+platform and execute it on a UNIX server. (Perl doesn't like getting
+carriage returns in the code it parses.)
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="4_Eval_perl_code_into_a_subrout">4. Eval perl code into a subroutine</A></H2>
+<P>
+The next step generates a subroutine out of your Perl code. In the above
+example it looks like:
+
+<P>
+sub foo { <CODE>$a</CODE> = ``This '>' is a greater sign'' }
+
+<P>
+The subroutine is now stored in the Perl interpreter in its internal
+precompiled format and can be called later as often as necessary without
+doing steps 1-4 again. Embperl recognizes if you request the same document
+a second time and will just call the compiled subroutine. This will also
+speed up the execution of dynamic tables and loops, because the code inside
+must be compiled only on the first iteration.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="5_Call_the_subroutine">5. Call the subroutine</A></H2>
+<P>
+Now the subroutine can be called to actually execute the code.
+
+<P>
+If Embperl isn't executing a [+ ... +] block we are done. If it is a [+ ...
++] block, Embperl needs to generate output, so it continues.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="6_Escape_special_characters_in_">6. Escape special characters in the return value</A></H2>
+<P>
+Our example returns the string:
+
+<P>
+``This '>' is a greater sign''
+
+<P>
+The greater sign is literal text (and not a closing html tag), so according
+to the HTML specification it must be sent as &gt; to the browser. In
+most cases, this won't be a problem, because the browser will display the
+correct text if we send a literal '>'. Also we could have directly
+written &gt; in our Perl string. But when the string is, for example,
+the result of a database query and/or includes characters from national
+character sets, it's absolutely necessary to send them correctly-escaped to
+the browser to get the desired result.
+
+<P>
+A special case is the <A> HTML tag. Since it includes a URL, the text
+must be URL-escaped instead of HTML-escaped. This means special characters
+like `&' must be sent by their hexadecimal ASCII code and blanks must
+be translated to a `+' sign. If you do not do this, your browser may not be
+able to interpret the URL correctly.
+
+<P>
+Example:
+
+<P>
+<PRE> <A HREF="<A HREF="http://host/script?name=">http://host/script?name=</A>[+$n+]">
+</PRE>
+<P>
+When <CODE>$n</CODE> is ``My name'' the requested URL, when you click on
+the hyperlink, will be
+
+<P>
+<PRE> <A HREF="http://host/script?name=My+name">http://host/script?name=My+name</A>
+</PRE>
+<P>
+In some cases it is useful to disable escaping. This can be done by the
+variable <STRONG>$escmode</STRONG>.
+
+<P>
+Example: (For better readability, we assume that optRawInput is set.
+Without it, you need to cover the Embperl pre-processing described in steps
+1-3.)
+
+<P>
+<PRE> [+ "<FONT COLOR=5>" +]
+</PRE>
+<P>
+<PRE> This will be sent to the browser as &lt;FONT COLOR=5&gt;, so you
+ will see the tag on the browser screen instead of the browser
+ switching the color.
+</PRE>
+<P>
+<PRE> [+ local $escmode=0 ; "<FONT COLOR=5>" +]
+</PRE>
+<P>
+<PRE> This will (locally) turn off escaping and send the text as a plain
+ HTML tag to the browser, so the color of the output will change.
+</PRE>
+<P>
+<PRE> NOTE: You cannot set $escmode more than once inside a [+ ... +] block.
+ Embperl uses the first setting of $escmode it encounters inside the block.
+ If you need to change $escmode more than once, you must use muliple
+ [+ ... +] blocks.
+
+</PRE>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="7_Send_the_return_value_as_outp">7. Send the return value as output to the destination
+(browser/file)</A></H2>
<P>
-To get the best performace from Embperl, it is necessary to restrict
-logging to a minimum. You can drastically slow down Embperl if you enable
-all logging options. (This is why `make test' takes a while to run.) You
-should <STRONG>never</STRONG> enable <STRONG>dbgFlushOutput</STRONG>, <STRONG>dbgFlushLog</STRONG> or
-<STRONG>dbgCacheDisable</STRONG> in a production environment. More debugging options are useful for
-development where it doesn't matter if the request takes a little bit
-longer, but on a heavily-loaded server they should be disabled. Addtionaly
-the options <EM>optDisableChdir</EM>, <EM>optDisableHtmlScan</EM>,
-<EM>optDisableCleanup</EM> have consequences for the performance.
+Now everything is done and the output can be sent to the browser. If you
+haven't set dbgEarlyHttpHeaders, the output is buffered until the
+successful completion of document execution of the document, and is sent to
+the browser along with the HTTP headers. If an error occurs, an error
+document is sent instead.
<P>
-Also take a look at <STRONG>mod_perl_tuning.pod</STRONG> for general ideas about performance.
+The content length and every <META HTTP-EQUIV=...> is added to the
+HTTP header before it is sent. If Embperl is executed as a subrequest or
+the output is going to a file, no http header is sent.
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.10.html">PREV (Inside Embperl - How the embedded Perl code is actually processed)</a>] [<a href="Embperl.pod.12.html">NEXT (Bugs)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.10.html">PREV (Input/Output Functions)</a>] [<a href="Embperl.pod.12.html">NEXT (Performance)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.6 +14 -10 modperl-site/embperl/Embperl.pod.12.html
Index: Embperl.pod.12.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.12.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Embperl.pod.12.html 1999/05/10 20:36:56 1.5
+++ Embperl.pod.12.html 2000/02/20 20:29:32 1.6
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Bugs</TITLE>
+<TITLE>Performance</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Bugs">Bugs</a></strong></h1>
+<A NAME="Performance">Performance</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,18 +16,22 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.11.html">PREV (Performance)</a>] [<a href="Embperl.pod.13.html">NEXT (Compatibility)</a>] <br><hr>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.11.html">PREV (Inside Embperl - How the embedded Perl code is actually processed)</a>] [<a href="Embperl.pod.13.html">NEXT (Bugs)</a>] <br><hr>
<P>
-None known.
+To get the best performace from Embperl, it is necessary to restrict
+logging to a minimum. You can drastically slow down Embperl if you enable
+all logging options. (This is why `make test' takes a while to run.) You
+should <STRONG>never</STRONG> enable <STRONG>dbgFlushOutput</STRONG>, <STRONG>dbgFlushLog</STRONG> or
+<STRONG>dbgCacheDisable</STRONG> in a production environment. More debugging options are useful for
+development where it doesn't matter if the request takes a little bit
+longer, but on a heavily-loaded server they should be disabled. Addtionaly
+the options <EM>optDisableChdir</EM>, <EM>optDisableHtmlScan</EM>,
+<EM>optDisableCleanup</EM> have consequences for the performance.
<P>
-Under perl5.004 there are memory leaks. This is not an Embperl bug, but can
-cause your httpd to grow endlessly when running under mod_perl. Please
-upgrade to perl5.004_04 to fix this. You should also upgrade to a mod_perl
-version higher than 1.07_01 as soon as possible, because until 1.07_01
-there is a memory leak in Apache->push_handler.
+Also take a look at <STRONG>mod_perl_tuning.pod</STRONG> for general ideas about performance.
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.11.html">PREV (Performance)</a>] [<a href="Embperl.pod.13.html">NEXT (Compatibility)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.11.html">PREV (Inside Embperl - How the embedded Perl code is actually processed)</a>] [<a href="Embperl.pod.13.html">NEXT (Bugs)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.9 +10 -49 modperl-site/embperl/Embperl.pod.13.html
Index: Embperl.pod.13.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.13.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- Embperl.pod.13.html 1999/08/30 04:24:12 1.8
+++ Embperl.pod.13.html 2000/02/20 20:29:32 1.9
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Compatibility</TITLE>
+<TITLE>Bugs</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Compatibility">Compatibility</a></strong></h1>
+<A NAME="Bugs">Bugs</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,57 +16,18 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.12.html">PREV (Bugs)</a>] [<a href="Embperl.pod.14.html">NEXT (Support)</a>] <br> <UL>
-
- <LI><A href="Embperl.pod.13.html#on_Linux_2_x_with">on Linux 2.x with</A>
- <LI><A href="Embperl.pod.13.html#on_Windows_NT_4_0_with">on Windows NT 4.0 with</A>
- <LI><A href="Embperl.pod.13.html#on_Windows_95_98_with">on Windows 95/98 with</A>
- </UL>
-<hr>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.12.html">PREV (Performance)</a>] [<a href="Embperl.pod.14.html">NEXT (Compatibility)</a>] <br><hr>
<P>
-I have tested Embperl succesfully
+None known.
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="on_Linux_2_x_with">on Linux 2.x with</A></H2>
-<DL>
-<DT><STRONG><A NAME="item_perl5">perl5.004_04</A></STRONG><DD>
-<DT><STRONG><A NAME="item_perl5">perl5.005_03</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.2.5</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.2.6</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.3.0</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.3.1</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.3.2</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.3.3</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.3.4</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.3.5</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_1">apache_1.3.6</A></STRONG><DD>
-<DT><STRONG><A NAME="item_apache_ssl">apache_ssl (Ben SSL)</A></STRONG><DD>
-<DT><STRONG><A NAME="item_Stronghold">Stronghold 2.2</A></STRONG><DD>
-<DT><STRONG>Stronghold 2.4.1</STRONG><DD>
-<DT><STRONG><A NAME="item_Apache_1">Apache_1.3.3 with mod_ssl 2.0.13</A></STRONG><DD>
-<DT><STRONG><A NAME="item_Apache_1">Apache_1.3.6 with mod_ssl 2.3.5</A></STRONG><DD>
-</DL>
<P>
-I know from other people that it works on many other UNIX systems
+Under perl5.004 there are memory leaks. This is not an Embperl bug, but can
+cause your httpd to grow endlessly when running under mod_perl. Please
+upgrade to perl5.004_04 to fix this. You should also upgrade to a mod_perl
+version higher than 1.07_01 as soon as possible, because until 1.07_01
+there is a memory leak in Apache->push_handler.
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="on_Windows_NT_4_0_with">on Windows NT 4.0 with</A></H2>
-<DL>
-<DT><STRONG>perl5.004_04</STRONG><DD>
-<DT><STRONG><A NAME="item_perl5">perl5.005</A></STRONG><DD>
-<DT><STRONG>apache_1.3.1</STRONG><DD>
-<DT><STRONG>apache_1.3.6</STRONG><DD>
-</DL>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="on_Windows_95_98_with">on Windows 95/98 with</A></H2>
-<DL>
-<DT><STRONG><A NAME="item_perl5">perl5.004_02 (binary distribution, only Offline Mode)</A></STRONG><DD>
-<DT><STRONG><A NAME="item_perl5">perl5.005_02 + apache_1.3.6</A></STRONG><DD>
-</DL>
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.12.html">PREV (Bugs)</a>] [<a href="Embperl.pod.14.html">NEXT (Support)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.12.html">PREV (Performance)</a>] [<a href="Embperl.pod.14.html">NEXT (Compatibility)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.9 +42 -42 modperl-site/embperl/Embperl.pod.14.html
Index: Embperl.pod.14.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.14.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- Embperl.pod.14.html 1999/09/08 05:19:37 1.8
+++ Embperl.pod.14.html 2000/02/20 20:29:32 1.9
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Support</TITLE>
+<TITLE>Compatibility</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Support">Support</a></strong></h1>
+<A NAME="Compatibility">Compatibility</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,57 +16,57 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.13.html">PREV (Compatibility)</a>] [<a href="Embperl.pod.15.html">NEXT (References)</a>] <br> <UL>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.13.html">PREV (Bugs)</a>] [<a href="Embperl.pod.15.html">NEXT (Support)</a>] <br> <UL>
- <LI><A href="Embperl.pod.14.html#Feedback_and_Bug_Reports">Feedback and Bug Reports</A>
- <LI><A href="Embperl.pod.14.html#Commerical_Support">Commerical Support</A>
+ <LI><A href="Embperl.pod.14.html#on_Linux_2_x_with">on Linux 2.x with</A>
+ <LI><A href="Embperl.pod.14.html#on_Windows_NT_4_0_with">on Windows NT 4.0 with</A>
+ <LI><A href="Embperl.pod.14.html#on_Windows_95_98_with">on Windows 95/98 with</A>
</UL>
<hr>
<P>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Feedback_and_Bug_Reports">Feedback and Bug Reports</A></H2>
-<P>
-Please let me know if you use or test this module. Bugs, questions,
-suggestions for things you would find useful, etc., are discussed on the
-mod_perl mailing list.
+I have tested Embperl succesfully
<P>
->From the mod_perl README: The Apache/Perl mailing list (<A
-HREF="mailto:modperl@apache.org">modperl@apache.org</A>) is available for
-mod_perl users and developers to share ideas, solve problems and discuss
-things related to mod_perl and the Apache::* (and Embperl) modules. To
-subscribe to this list, send mail to <A
-HREF="mailto:majordomo@apache.org">majordomo@apache.org</A> with the string
-``subscribe modperl'' in the body.
-
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="on_Linux_2_x_with">on Linux 2.x with</A></H2>
+<DL>
+<DT><STRONG><A NAME="item_perl5">perl5.004_04</A></STRONG><DD>
+<DT><STRONG><A NAME="item_perl5">perl5.005_03</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.2.5</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.2.6</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.3.0</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.3.1</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.3.2</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.3.3</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.3.4</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.3.5</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_1">apache_1.3.6</A></STRONG><DD>
+<DT><STRONG><A NAME="item_apache_ssl">apache_ssl (Ben SSL)</A></STRONG><DD>
+<DT><STRONG><A NAME="item_Stronghold">Stronghold 2.2</A></STRONG><DD>
+<DT><STRONG>Stronghold 2.4.1</STRONG><DD>
+<DT><STRONG><A NAME="item_Apache_1">Apache_1.3.3 with mod_ssl 2.0.13</A></STRONG><DD>
+<DT><STRONG><A NAME="item_Apache_1">Apache_1.3.6 with mod_ssl 2.3.5</A></STRONG><DD>
+</DL>
<P>
-There is a hypermail archive for this list available from: <A
-HREF="http://outside.organic.com/mail-archives/modperl/">http://outside.organic.com/mail-archives/modperl/</A>
+I know from other people that it works on many other UNIX systems
-
<P>
-There is an Epigone archive for the mod_perl mailing list at <A
-HREF="http://forum.swarthmore.edu/epigone/modperl">http://forum.swarthmore.edu/epigone/modperl</A>
-
-
-<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Commerical_Support">Commerical Support</A></H2>
-<P>
-You can get free support on the mod_perl mailing list (see above). If you
-need commercial support, ecos can provide it for you. We offer:
-
-<UL>
-<LI><STRONG><A NAME="item_Consulting">Consulting and assitance for you and your programmers</A></STRONG>
-<LI><STRONG><A NAME="item_Planning">Planning of your dynamic website</A></STRONG>
-<LI><STRONG><A NAME="item_Creating">Creating of parts or a whole website</A></STRONG>
-<LI><STRONG><A NAME="item_Fixing">Fixing bugs in Embperl (also available for mod_perl)</A></STRONG>
-<LI><STRONG><A NAME="item_Adding">Adding new features</A></STRONG>
-</UL>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="on_Windows_NT_4_0_with">on Windows NT 4.0 with</A></H2>
+<DL>
+<DT><STRONG>perl5.004_04</STRONG><DD>
+<DT><STRONG><A NAME="item_perl5">perl5.005</A></STRONG><DD>
+<DT><STRONG>apache_1.3.1</STRONG><DD>
+<DT><STRONG>apache_1.3.6</STRONG><DD>
+</DL>
<P>
-You can reach us via <A HREF="http://www.ecos.de">http://www.ecos.de</A> or
-<A HREF="mailto:info@ecos.de">info@ecos.de</A>
-
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.13.html">PREV (Compatibility)</a>] [<a href="Embperl.pod.15.html">NEXT (References)</a>] <br>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="on_Windows_95_98_with">on Windows 95/98 with</A></H2>
+<DL>
+<DT><STRONG><A NAME="item_perl5">perl5.004_02 (binary distribution, only Offline Mode)</A></STRONG><DD>
+<DT><STRONG><A NAME="item_perl5">perl5.005_02 + apache_1.3.6</A></STRONG><DD>
+</DL>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.13.html">PREV (Bugs)</a>] [<a href="Embperl.pod.15.html">NEXT (Support)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.10 +48 -31 modperl-site/embperl/Embperl.pod.15.html
Index: Embperl.pod.15.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.15.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- Embperl.pod.15.html 1999/09/08 05:19:37 1.9
+++ Embperl.pod.15.html 2000/02/20 20:29:32 1.10
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>References</TITLE>
+<TITLE>Support</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="References">References</a></strong></h1>
+<A NAME="Support">Support</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,46 +16,63 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.14.html">PREV (Support)</a>] [<a href="Embperl.pod.16.html">NEXT (Author)</a>] <br> <UL>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.14.html">PREV (Compatibility)</a>] [<a href="Embperl.pod.16.html">NEXT (References)</a>] <br> <UL>
- <LI><A href="Embperl.pod.15.html#Information">Information</A>
- <LI><A href="Embperl.pod.15.html#Download">Download</A>
- <LI><A href="Embperl.pod.15.html#CVS">CVS</A>
+ <LI><A href="Embperl.pod.15.html#Feedback_and_Bug_Reports">Feedback and Bug Reports</A>
+ <LI><A href="Embperl.pod.15.html#Commerical_Support">Commerical Support</A>
</UL>
<hr>
<P>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Information">Information</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Feedback_and_Bug_Reports">Feedback and Bug Reports</A></H2>
<P>
-<PRE> mod_perl <A HREF="http://perl.apache.org/">http://perl.apache.org/</A>
- mod_perl FAQ <A HREF="http://perl.apache.org/faq">http://perl.apache.org/faq</A>
- Embperl <A HREF="http://perl.apache.org/embperl/">http://perl.apache.org/embperl/</A>
- Embperl (german) <A HREF="http://www.ecos.de/embperl/">http://www.ecos.de/embperl/</A>
- DBIx::Recordset <A HREF="ftp://ftp.dev.ecos.de/pub/perl/dbi">ftp://ftp.dev.ecos.de/pub/perl/dbi</A>
- apache web server <A HREF="http://www.apache.org/">http://www.apache.org/</A>
- ben-ssl (free httpsd) <A HREF="http://www.apache-ssl.org/">http://www.apache-ssl.org/</A>
- stronghold (commerical httpsd) <A HREF="http://www.c2.net/">http://www.c2.net/</A>
- europe <A HREF="http://www.eu.c2.net/">http://www.eu.c2.net/</A>
- other Apache modules <A HREF="http://perl.apache.org/src/apache-modlist.html">http://perl.apache.org/src/apache-modlist.html</A>
-</PRE>
+Please let me know if you use or test this module. Bugs, questions,
+suggestions for things you would find useful, etc., are discussed on the
+mod_perl mailing list. If you have a site that is using Embperl, I would
+love to mention it in list of sites using Embperl
+(http://perl.apache.org/embperl/Sites.pod.1.html). Please drop me a mail
+with a short description, if your site uses Embperl.
+
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Download">Download</A></H2>
+>From the mod_perl README: The Apache/Perl mailing list (<A
+HREF="mailto:modperl@apache.org">modperl@apache.org</A>) is available for
+mod_perl users and developers to share ideas, solve problems and discuss
+things related to mod_perl and the Apache::* modules. To subscribe to this
+list, send mail to <A
+HREF="mailto:modperl-subscribe@apache.org">modperl-subscribe@apache.org</A>
+with the string ``subscribe modperl'' in the body. To unsubscribe send
+email to <A
+HREF="mailto:modperl-unsubscribe@apache.org,">modperl-unsubscribe@apache.org,</A>
+with body ``unsubscribe youremailaddress''.
+
+<P>
+There is a hypermail archive for this list available from: <A
+HREF="http://outside.organic.com/mail-archives/modperl/">http://outside.organic.com/mail-archives/modperl/</A>
+
+
<P>
-<PRE> mod_perl <A HREF="http://www.perl.com/CPAN/modules/by-module/Apache">http://www.perl.com/CPAN/modules/by-module/Apache</A>
- Embperl <A HREF="ftp://ftp.dev.ecos.de/pub/perl/embperl">ftp://ftp.dev.ecos.de/pub/perl/embperl</A>
- DBIx::Recordset <A HREF="ftp://ftp.dev.ecos.de/pub/perl/dbi">ftp://ftp.dev.ecos.de/pub/perl/dbi</A>
-
- Win NT/95/98 binarys
- Apache/perl/
- mod_perl/Embperl <A HREF="http://www.perl.com/CPAN/authors/Jeffrey_Baker/">http://www.perl.com/CPAN/authors/Jeffrey_Baker/</A>
-</PRE>
+There is an Epigone archive for the mod_perl mailing list at <A
+HREF="http://forum.swarthmore.edu/epigone/modperl">http://forum.swarthmore.edu/epigone/modperl</A>
+
+
<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="CVS">CVS</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Commerical_Support">Commerical Support</A></H2>
+<P>
+You can get free support on the mod_perl mailing list (see above). If you
+need commercial support, ecos can provide it for you. We offer:
+
+<UL>
+<LI><STRONG><A NAME="item_Consulting">Consulting and assitance for you and your programmers</A></STRONG>
+<LI><STRONG><A NAME="item_Planning">Planning of your dynamic website</A></STRONG>
+<LI><STRONG><A NAME="item_Creating">Creating of parts or a whole website</A></STRONG>
+<LI><STRONG><A NAME="item_Fixing">Fixing bugs in Embperl (also available for mod_perl)</A></STRONG>
+<LI><STRONG><A NAME="item_Adding">Adding new features</A></STRONG>
+</UL>
<P>
-The lastest developements are available from a CVS. Look at <A HREF="CVS.pod.1.html#INTRO">"perldoc CVS.pod"</A> for a detailed description.
+You can reach us via <A HREF="http://www.ecos.de">http://www.ecos.de</A> or
+<A HREF="mailto:info@ecos.de">info@ecos.de</A>
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.14.html">PREV (Support)</a>] [<a href="Embperl.pod.16.html">NEXT (Author)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.14.html">PREV (Compatibility)</a>] [<a href="Embperl.pod.16.html">NEXT (References)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.4 +40 -5 modperl-site/embperl/Embperl.pod.16.html
Index: Embperl.pod.16.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.16.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Embperl.pod.16.html 1999/05/10 20:36:58 1.3
+++ Embperl.pod.16.html 2000/02/20 20:29:32 1.4
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Author</TITLE>
+<TITLE>References</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Author">Author</a></strong></h1>
+<A NAME="References">References</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,11 +16,46 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.15.html">PREV (References)</a>] <br><hr>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.15.html">PREV (Support)</a>] [<a href="Embperl.pod.17.html">NEXT (Author)</a>] <br> <UL>
+
+ <LI><A href="Embperl.pod.16.html#Information">Information</A>
+ <LI><A href="Embperl.pod.16.html#Download">Download</A>
+ <LI><A href="Embperl.pod.16.html#CVS">CVS</A>
+ </UL>
+<hr>
+<P>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Information">Information</A></H2>
+<P>
+<PRE> mod_perl <A HREF="http://perl.apache.org/">http://perl.apache.org/</A>
+ mod_perl FAQ <A HREF="http://perl.apache.org/faq">http://perl.apache.org/faq</A>
+ Embperl <A HREF="http://perl.apache.org/embperl/">http://perl.apache.org/embperl/</A>
+ Embperl (german) <A HREF="http://www.ecos.de/embperl/">http://www.ecos.de/embperl/</A>
+ DBIx::Recordset <A HREF="ftp://ftp.dev.ecos.de/pub/perl/dbi">ftp://ftp.dev.ecos.de/pub/perl/dbi</A>
+ apache web server <A HREF="http://www.apache.org/">http://www.apache.org/</A>
+ ben-ssl (free httpsd) <A HREF="http://www.apache-ssl.org/">http://www.apache-ssl.org/</A>
+ stronghold (commerical httpsd) <A HREF="http://www.c2.net/">http://www.c2.net/</A>
+ europe <A HREF="http://www.eu.c2.net/">http://www.eu.c2.net/</A>
+ other Apache modules <A HREF="http://perl.apache.org/src/apache-modlist.html">http://perl.apache.org/src/apache-modlist.html</A>
+</PRE>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Download">Download</A></H2>
+<P>
+<PRE> mod_perl <A HREF="http://www.perl.com/CPAN/modules/by-module/Apache">http://www.perl.com/CPAN/modules/by-module/Apache</A>
+ Embperl <A HREF="ftp://ftp.dev.ecos.de/pub/perl/embperl">ftp://ftp.dev.ecos.de/pub/perl/embperl</A>
+ DBIx::Recordset <A HREF="ftp://ftp.dev.ecos.de/pub/perl/dbi">ftp://ftp.dev.ecos.de/pub/perl/dbi</A>
+
+ Win NT/95/98 binarys
+ Apache/perl/
+ mod_perl/Embperl <A HREF="ftp://theoryx5.uwinnipeg.ca/pub/other/">ftp://theoryx5.uwinnipeg.ca/pub/other/</A>
+</PRE>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="CVS">CVS</A></H2>
<P>
-G. Richter (<A HREF="mailto:richter@dev.ecos.de">richter@dev.ecos.de</A>)
+The lastest developements are available from a CVS. Look at <A HREF="CVS.pod.1.html#INTRO">"perldoc CVS.pod"</A> for a detailed description.
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.15.html">PREV (References)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.15.html">PREV (Support)</a>] [<a href="Embperl.pod.17.html">NEXT (Author)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.18 +280 -452 modperl-site/embperl/Embperl.pod.2.html
Index: Embperl.pod.2.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.2.html,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- Embperl.pod.2.html 2000/02/11 22:34:16 1.17
+++ Embperl.pod.2.html 2000/02/20 20:29:32 1.18
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Runtime configuration</TITLE>
+<TITLE>Operating-Modes</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Runtime_configuration">Runtime configuration</a></strong></h1>
+<A NAME="Operating_Modes">Operating-Modes</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,639 +16,467 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.1.html">PREV (Operating-Modes)</a>] [<a href="Embperl.pod.3.html">NEXT (SYNTAX)</a>] <br> <UL>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.1.html">PREV (DESCRIPTION)</a>] [<a href="Embperl.pod.3.html">NEXT (Runtime configuration)</a>] <br> <UL>
- <LI><A href="Embperl.pod.2.html#EMBPERL_FILESMATCH">EMBPERL_FILESMATCH</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_ALLOW_only_1_2b10_and_a">EMBPERL_ALLOW (only 1.2b10 and above)</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_PATH_1_3b1_and_above_">EMBPERL_PATH (1.3b1 and above)</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COMPARTMENT">EMBPERL_COMPARTMENT</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_ESCMODE">EMBPERL_ESCMODE</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_LOG">EMBPERL_LOG</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_PACKAGE">EMBPERL_PACKAGE</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_OPTIONS">EMBPERL_OPTIONS</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_INPUT_FUNC">EMBPERL_INPUT_FUNC</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_OUTPUT_FUNC">EMBPERL_OUTPUT_FUNC</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_MAILHOST">EMBPERL_MAILHOST</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_MAILFROM">EMBPERL_MAILFROM </A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_MAILDEBUG">EMBPERL_MAILDEBUG </A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_MAIL_ERRORS_TO">EMBPERL_MAIL_ERRORS_TO</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COOKIE_NAME">EMBPERL_COOKIE_NAME</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COOKIE_DOMAIN">EMBPERL_COOKIE_DOMAIN</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COOKIE_PATH">EMBPERL_COOKIE_PATH</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COOKIE_EXPIRES">EMBPERL_COOKIE_EXPIRES</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_SESSION_CLASSES">EMBPERL_SESSION_CLASSES</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_SESSION_ARGS">EMBPERL_SESSION_ARGS</A>
+ <LI><A href="Embperl.pod.2.html#Offline">Offline</A>
+ <LI><A href="Embperl.pod.2.html#As_a_CGI_script">As a CGI script</A>
+ <LI><A href="Embperl.pod.2.html#From_mod_perl_Apache_httpd_">From mod_perl (Apache httpd)</A>
+ <LI><A href="Embperl.pod.2.html#By_calling_HTML_Embperl_Execut">By calling HTML::Embperl::Execute (\%param)</A>
+ <LI><A href="Embperl.pod.2.html#Helper_functions_for_Execute">Helper functions for Execute</A>
+ <LI><A href="Embperl.pod.2.html#EXAMPLES_for_Execute_">EXAMPLES for Execute:</A>
</UL>
<hr>
<P>
-The runtime configuration is done by setting environment variables, either
-on the command line (when working offline) or in your web server's
-configuration file. Most HTTP servers understand
+Embperl can operate in one of four modes:
<P>
-SetEnv <var> <value>
-
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Offline">Offline</A></H2>
<P>
-If you are using Apache and mod_perl you can use
+Converts an HTML file with embedded Perl statements into a standard HTML
+file.
<P>
-PerlSetEnv <var> <value>
+<STRONG>embpexec.pl [-o outputfile] [-l logfile] [-d debugflags] htmlfile
+[query_string]</STRONG>
-<P>
-The advantage of PerlSetEnv over SetEnv is that it can be used on a per
-directory/virtual host basis.
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_FILESMATCH">EMBPERL_FILESMATCH</A></H2>
-<P>
-If specified, only files which match the given <STRONG>perl regular expression</STRONG> will be processed by Embperl, all other files will be handled by the
-standard Apache handler. This can be useful if you have Embperl documents
-and non Embperl documents (e.g. gifs) cohabitating in the same directory.
-EMBPERL_FILESMATCH works only under mod_perl.
-<P>
-<PRE> Example:
- # Only files which end with .htm will processed by Embperl
- PerlSetEnv EMBPERL_FILESMATCH \.htm$
-</PRE>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_ALLOW_only_1_2b10_and_a">EMBPERL_ALLOW (only 1.2b10 and above)</A></H2>
<P>
-If specified, only files which match the given <STRONG>perl regular expression</STRONG> will be processed by Embperl, all other files will return FORBIDDEN.
-Especialy in a CGI environenemt this can be usefull to make a server more
-secure.
+<STRONG>embpexec.bat [-o outputfile] [-l logfile] [-d debugflags] htmlfile
+[query_string]</STRONG>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_PATH_1_3b1_and_above_">EMBPERL_PATH (1.3b1 and above)</A></H2>
-<P>
-Can contain a colon separated file search path. When a file is processed
-and the filename does not contain a path, <EM>Embperl</EM> searches all the specified directories for that file.
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COMPARTMENT">EMBPERL_COMPARTMENT</A></H2>
-<P>
-Gives the name of the compartment from which to take the opcode mask. (See
-the chapter about <A href="Embperl.pod.7.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> for more details.)
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_ESCMODE">EMBPERL_ESCMODE</A></H2>
<P>
-Specifies the initial value for <A href="Embperl.pod.5.html#_escmode">$escmode</A> (see below).
+Use embpexec.pl on Unix systems and embpexec.bat on Win32 systems.
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_LOG">EMBPERL_LOG</A></H2>
+<DL>
+<DT><STRONG><A NAME="item_htmlfile">htmlfile</A></STRONG><DD>
<P>
-Gives the location of the log file. This will contain information about
-what Embperl is doing. How much information depends on the debug settings
-(see <A href="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> below). The log output is intended to show what your embedded Perl code is
-doing and to help debug it. The default is
-<STRONG>/tmp/embperl.log</STRONG>.
+The full pathname of the HTML file which should be processed by Embperl.
+<DT><STRONG><A NAME="item_query_string">query_string</A></STRONG><DD>
<P>
-<STRONG>NOTE:</STRONG> When running under mod_perl you need to use <STRONG>PerlSetEnv</STRONG> for setting the logfile path, and mod_perl >= 1.07_03 if you load
-Embperl at server startup (with PerlScript or PerlModule).
+Optional. Has the same meaning as the environment variable QUERY_STRING
+when invoked as a CGI script. That is, QUERY_STRING contains everything
+following the first ``?'' in a URL. <query_string> should be
+URL-encoded. The default is no query string.
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_PACKAGE">EMBPERL_PACKAGE</A></H2>
+<DT><STRONG><A NAME="item__o">-o outputfile</A></STRONG><DD>
<P>
-The name of the package where your code will be executed. By default,
-Embperl generates a unique package name for every file. This ensures that
-variables and functions from one file can not affect those from another
-file. (Any package's variables will still be accessible with explicit
-package names.)
+Optional. Gives the filename to which the output is written. The default is
+stdout.
+<DT><STRONG><A NAME="item__l">-l logfile</A></STRONG><DD>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A></H2>
+Optional. Gives the filename of the logfile. The default is
+/tmp/embperl.log.
+
+<DT><STRONG><A NAME="item__d">-d debugflags</A></STRONG><DD>
<P>
-Gives a virtual location where you can access the Embperl logfile with a
-browser. This feature is disabled (default) if EMBPERL_VIRTLOG is not
-specified. See also <A href="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> and dbgLogLink for an Example how to set it up in your srm.conf.
+Optional. Specifies the level of debugging (what is written to the log
+file). The default is nothing. See <A href="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> for exact values.
+</DL>
<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_OPTIONS">EMBPERL_OPTIONS</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="As_a_CGI_script">As a CGI script</A></H2>
<P>
-This bitmask specifies some options for the execution of Embperl. To
-specify multiple options, simply add the values together.
+Instead of a file being sent directly by the web server, the document is
+processed by the CGI script and the result is sent to the client.
-<DL>
-<DT><STRONG><A NAME="item_optDisableVarCleanup">optDisableVarCleanup = 1</A></STRONG><DD>
<P>
-Disables the automatic cleanup of variables at the end of each request.
+<STRONG>embpcgi.pl</STRONG>
-<DT><STRONG><A NAME="item_optDisableEmbperlErrorPage">optDisableEmbperlErrorPage = 2</A></STRONG><DD>
-<P>
-Tells Embperl to not send its own errorpage in case of failure, instead
-shows as much of the page as possible. Errors are only logged to the log
-file. Without this option, Embperl sends its own error page, showing all
-the errors which have occurred. If you have dbgLogLink enabled, every error
-will be a link to the corresponding location in the log file. This option
-has no effect if optReturnError is set.
-<DT><STRONG><A NAME="item_optReturnError">optReturnError = 262144</A></STRONG><DD>
-<P>
-With this option set Embperl sends no output in case of an error, instead
-it returns the error back to Apache or the calling programm. When running
-under mod_perl this gives you the chance to use the Apache <EM>ErrorDocument</EM>
-directive to show a custom error-document.
-<DT><STRONG><A NAME="item_optSafeNamespace">optSafeNamespace = 4</A></STRONG><DD>
<P>
-Tells Embperl to execute the embedded code in a safe namespace so the code
-cannot access data or code in any other package. (See the chapter about <A href="Embperl.pod.7.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> below for more details.)
+<STRONG>embpcgi.bat</STRONG>
-<DT><STRONG><A NAME="item_optOpcodeMask">optOpcodeMask = 8</A></STRONG><DD>
-<P>
-Tells Embperl to apply an operator mask. This gives you the chance to
-disallow special (unsafe) opcodes. (See the Chapter about
-<A href="Embperl.pod.7.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A>
-below for more details.)
-<DT><STRONG><A NAME="item_optRawInput">optRawInput = 16</A></STRONG><DD>
-<P>
-Causes Embperl not to pre-process the source for a Perl expression. (The
-only exception is that carriage returns will be removed, as Perl does not
-like them.) This option should be set when you are writing your code with
-an ASCII editor.
<P>
-If you are using a WYSIWYG editor which inserts unwanted HTML tags in your
-Perl expressions and escapes special charcaters automatically (e.g., `<'
-appears as `&lt;' in the source), you should not set this option.
-Embperl will automatically convert the HTML input back to the Perl
-expressions as you wrote them.
+Use embpcgi.pl on Unix systems and embpcgi.bat on Win32 systems.
-<DT><STRONG><A NAME="item_optEarlyHttpHeader">optEarlyHttpHeader = 64</A></STRONG><DD>
<P>
-Normally, HTTP headers are sent after a request is finished without error.
-This gives you the chance to set arbitrary HTTP headers within the page,
-and gives Embperl the chance to calculate the content length. Also Embperl
-watches out for errors and sends an errorpage instead of the document if
-something goes wrong. To do this, all the output is kept in memory until
-the whole request is processed, then the HTTP headers are sent, and then
-the document. This flag will cause the HTTP headers to be sent before the
-script is processed, and the script's output will be sent directly.
+If <CODE>embpcgi.pl/embpcgi.bat</CODE> is invoked without any parameters and the environment variable <STRONG>PATH_TRANSLATED</STRONG> is set, it runs itself as a CGI script. This means that form data is taken
+either from the environment variable <STRONG>QUERY_STRING</STRONG> or from stdin, depending on whether or not <STRONG>CONTENT_LENGTH</STRONG> is set. (This will be set by the web server depending on whether the
+request method is GET or POST). Input is taken from the file pointed to by <STRONG>PATH_TRANSLATED</STRONG> and the output is send to stdout. The logfile is generated at its default
+location, which is configurable via the environment variable <STRONG>EMBPERL_LOG</STRONG>.
-<DT><STRONG><A NAME="item_optDisableChdir">optDisableChdir = 128</A></STRONG><DD>
<P>
-Without this option, Embperl changes the currect directory to the one where
-the script resides. This gives you the chance to use relative pathnames.
-Since directory-changing takes up some millisecs, you can disable it with
-this option if you don't need it.
+To use this mode you must copy <STRONG>embpcgi.pl</STRONG> to your cgi-bin directory. You can invoke it with the URL <A
+HREF="http://www.domain.xyz/cgi-bin/embpcgi.pl/url/of/your/document.">http://www.domain.xyz/cgi-bin/embpcgi.pl/url/of/your/document.</A>
-<DT><STRONG><A NAME="item_optDisableFormData">optDisableFormData = 256</A></STRONG><DD>
-<P>
-This option disables the setup of <CODE>%fdat</CODE> and @ffld. Embperl will not do anything with the posted form data.
-<DT><STRONG><A NAME="item_optDisableHtmlScan">optDisableHtmlScan = 512</A></STRONG><DD>
<P>
-When set, this option disables the scanning of <STRONG>all</STRONG> html-tags. Embperl will only look for [+/-/!/$ ... $/!/-/+]. This will
-disable dynamic tables, processing of the input data and so on.
+The /url/of/your/document will be passed to Embperl by the web server.
+Normal processing (aliasing, etc.) takes place before the URI makes it to
+PATH_TRANSLATED.
-<DT><STRONG><A NAME="item_optDisableInputScan">optDisableInputScan = 1024</A></STRONG><DD>
<P>
-Disables processing of all input-related tags.
-(<INPUT><TEXTAREA><OPTION>)
+If you are running the Apache httpd, you can also define
+<STRONG>embpcgi.pl</STRONG> as a handler for a specific file extention or directory.
-<DT><STRONG><A NAME="item_optDisableTableScan">optDisableTableScan = 2048</A></STRONG><DD>
<P>
-Disables processing of all table-related tags.
-(<TABLE><TH><TR><TD><MENU><OL><SELECT><UL>)
-
+Example of Apache <CODE>srm.conf</CODE>:
-<DT><STRONG><A NAME="item_optDisableMetaScan">optDisableMetaScan = 4096</A></STRONG><DD>
<P>
-Disables processing of all meta tags. (<META HTTP-EQUIV>)
-
-<DT><STRONG><A NAME="item_optAllFormData">optAllFormData = 8192</A></STRONG><DD>
+<PRE> <Directory /path/to/your/html/docs>
+ Action text/html /cgi-bin/embperl/embpcgi.pl
+ </Directory>
+</PRE>
<P>
-This option will cause Embperl to insert all formfields in
-<CODE>%fdat</CODE> and @ffld, even if they are empty. Empty formfields will be inserted with an
-empty string. Without this option empty formfields will not be insert in
-<CODE>%fdat</CODE> and @ffld.
+<STRONG>NOTE 1</STRONG>: Out of security reasons, embpexec.pl must not be used anymore as CGI
+script!
-<DT><STRONG><A NAME="item_optRedirectStdout">optRedirectStdout = 16384</A></STRONG><DD>
<P>
-Redirects STDOUT to the Embperl output stream before every request and
-resets it afterwards. If set, you can use a normal Perl <STRONG>print</STRONG> inside any Perl block to output data. Without this option you can only
-output data by using the [+ ... +] block, or printing to the filehandle <STRONG>OUT</STRONG>.
+<STRONG>NOTE 2</STRONG>: CGI Scripts are not so secure. You should consider using <EM>EMBPERL_ALLOW</EM>
+to restrict the access to the rights documents.
-<DT><STRONG><A NAME="item_optUndefToEmptyValue">optUndefToEmptyValue = 32768</A></STRONG><DD>
<P>
-Normally if there is no value in <CODE>%fdat</CODE> for a specific input
-field, Embperl will leave it untouched. When this option is set, Embperl
-will handle the field as if an empty string was stored in
-<CODE>%fdat</CODE> for the field.
-
-<DT><STRONG><A NAME="item_optNoHiddenEmptyValue">optNoHiddenEmptyValue = 65536 (only 1.2b2 and above)</A></STRONG><DD>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="From_mod_perl_Apache_httpd_">From mod_perl (Apache httpd)</A></H2>
<P>
-Normally, if there is a value defined in <CODE>%fdat</CODE> for a specific
-input field, Embperl will output a hidden input element for it when you use <STRONG>hidden</STRONG>. When this option is set, Embperl will not output a hidden input element
-for this field when the value is a blank string.
+This works like the CGI-Script, but with the advantage that the script is
+compiled only once at server startup, where other one-time actions (such as
+opening files and databases) can take place. This will drastically reduce
+response times for the request. To use this you must compile <CODE>Apache httpd</CODE> with <CODE>mod_perl</CODE> and add <CODE>HTML::Embperl</CODE>
+as the <CODE>PerlHandler</CODE>.
-<DT><STRONG><A NAME="item_optAllowZeroFilesize">optAllowZeroFilesize = 131072 (only 1.2b2 and above)</A></STRONG><DD>
<P>
-Normaly Embperl reports NOT_FOUND (404) if a file of length zero is
-requested. With this option set Embperl will return an empty document.
+Example of Apache <CODE>srm.conf</CODE> or <CODE>httpd.conf</CODE>:
-<DT><STRONG><A NAME="item_optKeepSrcInMemory">optKeepSrcInMemory = 524288 (only 1.2b5 and above)</A></STRONG><DD>
<P>
-Tells Embperl to keep the source file in memory and not reload it on every
-request. (The precompiled Perlcode is always kept in memory, regardless of
-this flag)
-
-<DT><STRONG><A NAME="item_optKeepSpaces">optKeepSpaces = 1048576 (only 1.2b5 and above) = 0x100000,</A></STRONG><DD>
+<PRE> SetEnv EMBPERL_DEBUG 2285
+</PRE>
<P>
-Disable the removing of spaces and empty lines from the output. This is
-usefull for other sources then HTML.
-
-<DT><STRONG><A NAME="item_optOpenLogEarly">optOpenLogEarly = 2097152 (only 1.2b5 and above)</A></STRONG><DD>
+<PRE> Alias /embperl /path/to/embperl/eg
+</PRE>
<P>
-This option causeses Embperl to open the logfile as soon as it is loaded
-into memory. You can use this when you load Embperl via PerlModule under
-Apache, to open the log as root instead of the non-privileged user Apache
-runs as. =item optUncloseWarn = 4194304 (only 1.2b6 and above)
-
+<PRE> <Location /embperl/x>
+ SetHandler perl-script
+ PerlHandler HTML::Embperl
+ Options ExecCGI
+ </Location>
+</PRE>
<P>
-Disable the warnings about unclosed <CODE>if</CODE>, <CODE>while</CODE>, <CODE>table</CODE> etc. at the end of the file.
+Another possible setup is
-</DL>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_DEBUG">EMBPERL_DEBUG</A></H2>
+<PRE> SetEnv EMBPERL_DEBUG 2285
+</PRE>
<P>
-This is a bitmask which specifies what should be written to the log. To
-specify multiple debugflags, simply add the values together. The following
-values are defined:
-
-<DL>
-<DT><STRONG><A NAME="item_dbgStd">dbgStd = 1</A></STRONG><DD>
+<PRE> <Files *.epl>
+ SetHandler perl-script
+ PerlHandler HTML::Embperl
+ Options ExecCGI
+ </files>
+</PRE>
<P>
-Show minimum information.
-
-<DT><STRONG><A NAME="item_dbgMem">dbgMem = 2</A></STRONG><DD>
+<PRE> AddType text/html .epl
+</PRE>
<P>
-Show memory and scalar value allocation.
+Don't forget the <STRONG>AddType</STRONG>. In this setup, all files ending with .epl are processed by Embperl.
-<DT><STRONG><A NAME="item_dbgEval">dbgEval = 4</A></STRONG><DD>
<P>
-Show arguments to and results of evals.
+See the section <A href="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> (dbgLogLink and EMBPERL_VIRTLOG) to find out how you can configure Embperl
+so you can view the log file with your browser!
-<DT><STRONG><A NAME="item_dbgCmd">dbgCmd = 8</A></STRONG><DD>
<P>
-Show metacommands and HTML tags which are processed.
+<STRONG>NOTE</STRONG>: When mod_perl is compiled as loadable module (i.e. with USE_DSO) you
+<STRONG>must not</STRONG> load Embperl at server startup time!
-<DT><STRONG><A NAME="item_dbgEnv">dbgEnv = 16,</A></STRONG><DD>
<P>
-List every request's environment variables.
+<STRONG>See also</STRONG>: <A HREF="EmbperlObject.pod.cont.html">"perldoc EmbperlObject"</A> to see how to setup <EM>Embperl</EM> in a way to create your site out of small overwriteable objects.
-<DT><STRONG><A NAME="item_dbgForm">dbgForm = 32</A></STRONG><DD>
<P>
-Lists posted form data.
-
-<DT><STRONG><A NAME="item_dbgTab">dbgTab = 64</A></STRONG><DD>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="By_calling_HTML_Embperl_Execut">By calling HTML::Embperl::Execute (\%param)</A></H2>
<P>
-Show processing of dynamic tables.
+Execute can be used to call Embperl from your own modules/scripts (for
+example from a Apache::Registry or CGI script) or from within another
+Embperl page (only 1.2b1 or higher) to nest multiple Embperl pages (for
+example to store a common header or footer in an different file).
-<DT><STRONG><A NAME="item_dbgInput">dbgInput = 128</A></STRONG><DD>
<P>
-Show processing of HTML input tags.
+There are two forms you can use for calling Execute. A short form which
+only takes an filename and optional additional parameters or a long form
+which takes a hash reference as its argument. This gives it the chance to
+vary the parameters according to the job that should be done.
-<DT><STRONG><A NAME="item_dbgFlushOutput">dbgFlushOutput = 256</A></STRONG><DD>
<P>
-Flush Embperl's output after every write. This should only be set to help
-debug Embperl crashes, as it drastically slows down Embperl's operation.
+(See <STRONG>eg/x/Excute.pl</STRONG> for more detailed examples)
-<DT><STRONG><A NAME="item_dbgFlushLog">dbgFlushLog = 512</A></STRONG><DD>
<P>
-Flush Embperl's logfile output after every write. This should only be set
-to help debug Embperl crashes, as it drastically slows down Embperl's
-operation.
+<STRONG>See also</STRONG>: <A HREF="EmbperlObject.pod.cont.html">"perldoc EmbperlObject"</A> to see how to setup <EM>Embperl</EM> in a way to create your site out of small overwriteable objects and <A HREF="Mail.pod.cont.html">"perldoc HTML::Embperl::Mail"</A> how to use <EM>Embperl</EM> to send email.
-<DT><STRONG><A NAME="item_dbgAllCmds">dbgAllCmds = 1024</A></STRONG><DD>
<P>
-Logs all commands and HTML tags, whether or not they are really excuted or
-not. (It logs a `+' or `-' to tell you if they are executed.)
-
-<DT><STRONG><A NAME="item_dbgSource">dbgSource = 2048</A></STRONG><DD>
+<PRE> Execute($filename, $p1, $p2, $pn) ;
+</PRE>
<P>
-Logs the next piece of the HTML source to be processed. (NOTE: This
-generates a lot of output!)
+This will cause Embperl to interpret the file with the name
+<CODE>$filename</CODE> and, if specified, pass any additional parameters in
+the array @param (just like <CODE>@_</CODE> in a perl subroutine). The above example
+could also be written in the long form:
-<DT><STRONG><A NAME="item_dbgFunc">dbgFunc = 4096</A></STRONG><DD>
<P>
-This is only anvailable when Embperl is compiled with -DEPDEBUGALL, and is
-normally only used for debugging Embperl itself. Records all function
-entries to the logfile.
-
-<DT><STRONG><A NAME="item_dbgLogLink">dbgLogLink = 8192</A></STRONG><DD>
+<PRE> Execute ({inputfile => $filename,
+ param => [$p1, $p2, $pn]}) ;
+</PRE>
<P>
-Inserts a link at the top of each page which can be used to view the log
-for the current HTML file. See also <A href="Embperl.pod.2.html#EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A>.
+The possible items for hash of the long form are:
+<DL>
+<DT><STRONG><A NAME="item_inputfile">inputfile</A></STRONG><DD>
<P>
-Example:
+The file which should be used as source. If <STRONG>input</STRONG> is also specified, this parameter should be given a unique name to identify
+the source. Every time Embperl sees the same text in <STRONG>inputfile</STRONG>, it assumes that you compiled the same source - that means that Embperl
+uses the same package name as in your last call, and only recompiles the
+code if <STRONG>mtime</STRONG> has changed or is undefined.
-<P>
-<PRE> SetEnv EMBPERL_DEBUG 10477
- SetEnv EMBPERL_VIRTLOG /embperl/log
-</PRE>
-<P>
-<PRE> <Location /embperl/log>
- SetHandler perl-script
- PerlHandler HTML::Embperl
- Options ExecCGI
- </Location>
-</PRE>
-<DT><STRONG><A NAME="item_dbgDefEval">dbgDefEval = 16384</A></STRONG><DD>
+<DT><STRONG><A NAME="item_sub">sub</A></STRONG><DD>
<P>
-Shows every time new Perl code is compiled.
+Call the Embperl subroutine named by this <CODE>parameter(see</CODE> also <STRONG>"[$ sub $]"</STRONG>). Currently the subroutine must be in the same file or if it's in another
+file, the other file has to be imported first.
-<DT><STRONG><A NAME="item_dbgCacheDisable">dbgCacheDisable = 32768</A></STRONG><DD>
+<DT><STRONG><A NAME="item_input">input</A></STRONG><DD>
<P>
-Disables the use of the p-code cache. All Perl code is recompiled every
-time. (This should not be used in normal operation as it slows down Embperl
-dramatically.) This option is only here for debugging Embperl's cache
-handling. There is no guarantee that Embperl behaves the same with and
-without cache (actually is does not!)
+Reference to a string which contains the source. <STRONG>inputfile</STRONG> must also be specified to give a name for the source. The name can be any
+text.
-<DT><STRONG><A NAME="item_dbgHeadersIn">dbgHeadersIn = 262144</A></STRONG><DD>
+<DT><STRONG><A NAME="item_mtime">mtime</A></STRONG><DD>
<P>
-Log all HTTP headers which are sent from the browser.
+Last modification time of member <STRONG>input</STRONG>. If undef the code passed by input is always recompiled, else the code is
+only recompiled if mtime changes.
-<DT><STRONG><A NAME="item_dbgShowCleanup">dbgShowCleanup = 524288</A></STRONG><DD>
+<DT><STRONG><A NAME="item_outputfile">outputfile</A></STRONG><DD>
<P>
-Show every variable which is undef'd at the end of the request. For scalar
-variables, the value before undef'ing is logged.
+File to which the output should be written. If neither outputfile nor
+output is specified, ouput is written to stdout.
-<DT><STRONG><A NAME="item_dbgProfile">dbgProfile = 1048576 (only 1.2b4 and above)</A></STRONG><DD>
+<DT><STRONG><A NAME="item_output">output</A></STRONG><DD>
<P>
-When set every source line in the log file will also display the time until
-request was started. (<STRONG>dbgSource</STRONG> must also be set)
+Reference to a scalar where the output should be written to.
-<DT><STRONG><A NAME="item_dbgSession">dbgSession = 2097152 (only 1.2b4 and above)</A></STRONG><DD>
+<DT><STRONG><A NAME="item_import">import</A></STRONG><DD>
<P>
-Enables logging of session transactions.
+A value of zero tell's Embperl not to execute the page, but define all
+subrountines found inside. This is neccessary before calling them with
+Execute by the <STRONG>sub</STRONG>
+parameter or for an later import.
-<DT><STRONG><A NAME="item_dbgImport">dbgImport = 4194304 (only 1.2b5 and above)</A></STRONG><DD>
<P>
-Show how subroutines are imported in other namesapces
+A value of one tell's Embperl to define to subrountines inside the file (if
+not already done) and to import them as perl subroutines into the current
+namespace.
-</DL>
<P>
-A good value to start is <CODE>2285</CODE> or <CODE>10477</CODE> if you want to view the logfile with your browser. (Don't forget to set
-EMBPERL_VIRTLOG.) If Embperl crashes, add <CODE>512</CODE> so the logfile is flushed after every line is written and you can see where
-Embperl is when it crashes.
+See <STRONG>[$ sub $]</STRONG> metacommand and section about subroutines for more infos.
+<DT><STRONG><A NAME="item_req_rec">req_rec</A></STRONG><DD>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_INPUT_FUNC">EMBPERL_INPUT_FUNC</A></H2>
+NOTE: The req_rec parameter isn't necessary anymore in versions >= 1.2b2
+
<P>
-This directive gives you the possiblity to specify a non-standard way of
-fetching input. Normally, Embperl reads its input (source) from a file (or
-gets it from a scalar if you use <CODE>Execute</CODE>). Here, you can give the name of a Perl function which is called instead
-of reading the input from a file. The function must look like the
-following:
+If used under mod_perl, you should set the req_rec parameter to the Apache
+request record object provided by mod_perl.
+<DT><STRONG><A NAME="item_cleanup">cleanup</A></STRONG><DD>
<P>
-<PRE> InputFunc ($r, $in, $cacheargs, additional parameters...) ;
-</PRE>
+This value specifies if and when the cleanup of the package should be
+executed. (See <A href="Embperl.pod.5.html#Variable_scope_and_cleanup">Variable scope and cleanup</A> below for more information on cleanup)
+
<DL>
-<DT><STRONG><A NAME="item__r">$r</A></STRONG><DD>
+<DT><STRONG>cleanup = -1</STRONG><DD>
<P>
-Apache Request Record (see <STRONG>perldoc Apache</STRONG> for details)
+Never cleanup the variables
-<DT><STRONG><A NAME="item__in">$in</A></STRONG><DD>
+<DT><STRONG>cleanup = 0 or not specified</STRONG><DD>
<P>
-a reference to a scalar, to which the input should be returned.
+If running under mod_perl, cleanup is delayed until the connection to the
+client is closed, so it does not lengthen the response time to the client.
+If the Execute function is called more the once before the end of the
+request, all cleanups take place after the end of the request and not
+between calls to Execute.
-<P>
-<PRE> Example:
-</PRE>
<P>
-<PRE> open F, "filename" ;
- local $\ = undef ;
- $$in = <F> ;
- close F ;
-</PRE>
-<DT><STRONG><A NAME="item__cacheargs">$cacheargs</A></STRONG><DD>
-<P>
-a reference to a scalar, to which the modification time should be returned,
-alternativ (1.2.1 and up) you can return a reference to a hash with the
-elements <A href="Embperl.pod.1.html#item_mtime">mtime</A> and <A href="Embperl.pod.1.html#item_inputfile">inputfile</A>
-with are used to correcly cache the precompiled Perlcode.
+If running as a CGI or offline, cleanup takes place immediately.
-<P>
-<PRE> Example:
-</PRE>
-<P>
-<PRE> $$cacheargs = -M "filename" ;
-</PRE>
-<P>
-<PRE> or
-</PRE>
+<DT><STRONG>cleanup = 1</STRONG><DD>
<P>
-<PRE> $$cacheargs = { mtime => -M "filename", inputfile => "filename" } ;
-</PRE>
+Immediate cleanup
+
</DL>
+<DT><STRONG><A NAME="item_param">param</A></STRONG><DD>
<P>
-You can give <STRONG>additional parameters</STRONG> (which must be comma-separated) to <STRONG>EMBPERL_INPUT_FUNC</STRONG>
-which will then pass them as a string.
+Can be used to pass parameters to the Embperl document and back. Must
+contain a reference to an array.
-<P>
-<PRE> Example:
-</PRE>
-<P>
-<PRE> PerlSetEnv EMBPERL_INPUT_FUNC "InputFunc, foo, bar"
-</PRE>
-<P>
-<PRE> will call
-</PRE>
<P>
-<PRE> InputFunc ($r, $in, $mtime, 'foo', 'bar') ;
+<PRE> Example:
</PRE>
<P>
-<PRE> to get the input.
+<PRE> HTML::Embperl::Execute(..., param => [1, 2, 3]) ;
+ HTML::Embperl::Execute(..., param => \@parameters) ;
</PRE>
<P>
-<STRONG>EXAMPLE for an input function which does just the same as Embperl</STRONG>
-
+The array @param in the Embperl document is setup as an alias to the array. See
+eg/x/Excute.pl for a more detailed example.
-
-<P>
-<PRE> sub Input
-</PRE>
-<P>
-<PRE> {
- my ($r, $in, $mtime) = @_ ;
-</PRE>
-<P>
-<PRE> open F, $r -> filename or return NOT_FOUND ;
- local $\ = undef ;
- $$in = <F> ;
- close F ;
-</PRE>
+<DT><STRONG><A NAME="item_ffld">ffld and fdat</A></STRONG><DD>
<P>
-<PRE> $$mtime = -M $r -> filename ;
-
- return 0 ;
- }
-</PRE>
-<P>
-See also <A href="Embperl.pod.9.html#ProxyInput_r_in_mtime_sr">ProxyInput</A> below, for an input function which comes with Embperl.
+Could be used to setup the two Embperl predefined variables.
+<DT><STRONG><A NAME="item_firstline">firstline</A></STRONG><DD>
<P>
-NOTE: There are also two modules (<EM>HTML::EmbperlChain</EM> and <EM>Apache::EmbperlFilter</EM>) which provides you with the possibility to chain <EM>Embperl</EM> and other modules together.
+Specifies the first linenumber of the sourcefile (Default: 1)
+<DT><STRONG><A NAME="item_options">options</A></STRONG><DD>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_OUTPUT_FUNC">EMBPERL_OUTPUT_FUNC</A></H2>
-<P>
-This directive allows you to specify a non-standard way of dealing with
-output. Normally, Embperl sends its output (source) to a file/the browser
-(or to a scalar if you use <CODE>Execute</CODE>). Here, you can give the name of a Perl function which is called instead
-of sending the output to a file/the browser. The function must look like
-the following:
+Same as <A href="Embperl.pod.3.html#EMBPERL_OPTIONS">EMBPERL_OPTIONS</A> (see below), except for cleanup.
-<P>
-<PRE> OutputFunc ($r, $out, additional parameters...) ;
-</PRE>
-<DL>
-<DT><STRONG>$r</STRONG><DD>
<P>
-Apache Request Record (see <STRONG>perldoc Apache</STRONG> for details)
+<STRONG>NOTE:</STRONG> You should set the <STRONG>optDisableFormData</STRONG> if you have already read the form data from stdin while in a POST request.
+Otherwise Execute will hang and try to read the data a second time.
-<DT><STRONG><A NAME="item__out">$out</A></STRONG><DD>
+<DT><STRONG><A NAME="item_debug">debug</A></STRONG><DD>
<P>
-a reference to a scalar, which contains the output from Embperl
+Same as <A href="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> (see below).
-</DL>
+<DT><STRONG><A NAME="item_escmode">escmode</A></STRONG><DD>
<P>
-You can give <STRONG>additional parameters</STRONG> (which must be comma-separated) to <STRONG>EMBPERL_OUTPUT_FUNC</STRONG>, which will then pass them as a string.
+Same as <A href="Embperl.pod.3.html#EMBPERL_ESCMODE">EMBPERL_ESCMODE</A> (see below).
-<P>
-<PRE> Example:
-</PRE>
+<DT><STRONG><A NAME="item_package">package</A></STRONG><DD>
<P>
-<PRE> PerlSetEnv EMBPERL_OUTPUT_FUNC "OutputFunc, foo, bar"
-</PRE>
-<P>
-<PRE> will call
-</PRE>
-<P>
-<PRE> OutputFunc ($r, $out, 'foo', 'bar') ;
-</PRE>
-<P>
-<PRE> for output.
-</PRE>
-<P>
-<STRONG>EXAMPLE for an ouput function which does just the same as Embperl</STRONG>
-
-
+Same as <A href="Embperl.pod.3.html#EMBPERL_PACKAGE">EMBPERL_PACKAGE</A> (see below).
+<DT><STRONG><A NAME="item_virtlog">virtlog</A></STRONG><DD>
<P>
-<PRE> sub Output
-</PRE>
-<P>
-<PRE> {
- my ($r, $out) = @_ ;
-</PRE>
+Same as <A href="Embperl.pod.3.html#EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A> (see below). If <STRONG>virtlog</STRONG> is equal to <STRONG>uri</STRONG> the logfile is sent.
+
+<DT><STRONG><A NAME="item_allow">allow (1.2b10 and above)</A></STRONG><DD>
<P>
-<PRE> $r -> send_http_header ;
-</PRE>
+Same as <A href="Embperl.pod.3.html#EMBPERL_ALLOW_only_1_2b10_and_a">"EMBPERL_ALLOW"</A> (see below)
+
+<DT><STRONG><A NAME="item_path">path (1.3b1 and above)</A></STRONG><DD>
<P>
-<PRE> $r -> print ($$out) ;
-</PRE>
+Same as <A href="Embperl.pod.3.html#EMBPERL_PATH_1_3b1_and_above_">"EMBPERL_PATH"</A> (see below)
+
+<DT><STRONG><A NAME="item_uri">uri</A></STRONG><DD>
<P>
-<PRE> return 0 ;
- }
-</PRE>
+The URI of the request. Only needed for the virtlog feature.
+
+<DT><STRONG><A NAME="item_compartment">compartment</A></STRONG><DD>
<P>
-See also <A href="Embperl.pod.9.html#LogOutput_r_out_basepath_">LogOutput</A> below, for an output function which comes with Embperl.
+Same as <A href="Embperl.pod.3.html#EMBPERL_COMPARTMENT">EMBPERL_COMPARTMENT</A> (see below).
+<DT><STRONG><A NAME="item_input_func">input_func</A></STRONG><DD>
<P>
-NOTE: There are also two modules (<EM>HTML::EmbperlChain</EM> and <EM>Apache::EmbperlFilter</EM>) which provides you with the possibility to chain <EM>Embperl</EM> and other modules together.
+Same as <A href="Embperl.pod.3.html#EMBPERL_INPUT_FUNC">EMBPERL_INPUT_FUNC</A> (see below). Additionaly you can specify an code reference to an perl
+function, which is used as input function or an array reference, where the
+first element contains the code reference and further elements contains
+additional arguments passed to the function.
+<DT><STRONG><A NAME="item_output_func">output_func</A></STRONG><DD>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_MAILHOST">EMBPERL_MAILHOST</A></H2>
+Same as <A href="Embperl.pod.3.html#EMBPERL_OUTPUT_FUNC">EMBPERL_OUTPUT_FUNC</A> (see below). Additionaly you can specify an code reference to an perl
+function, which is used as output function or an array reference, where the
+first element contains the code reference and further elements contains
+additional arguments passed to the function.
+
+<DT><STRONG><A NAME="item_cookie_name">cookie_name</A></STRONG><DD>
<P>
-Specifies which host the <A href="Embperl.pod.8.html#MailFormTo_MailTo_Subject_R">MailFormTo</A> function uses as SMTP server. Default is <STRONG>localhost</STRONG>.
+Same as <A href="Embperl.pod.3.html#EMBPERL_COOKIE_NAME">EMBPERL_COOKIE_NAME</A> (see below).
+<DT><STRONG><A NAME="item_cookie_path">cookie_path</A></STRONG><DD>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_MAILFROM">EMBPERL_MAILFROM</A></H2>
+Same as <A href="Embperl.pod.3.html#EMBPERL_COOKIE_PATH">EMBPERL_COOKIE_PATH</A> (see below).
+
+<DT><STRONG><A NAME="item_cookie_domain">cookie_domain</A></STRONG><DD>
<P>
-(only 1.2.1 or above) Specifies which the email address that is used as
-sender by <A href="Embperl.pod.8.html#MailFormTo_MailTo_Subject_R">MailFormTo</A>. Default is <STRONG>www-server@server_name</STRONG>.
+Same as <A href="Embperl.pod.3.html#EMBPERL_COOKIE_DOMAIN">EMBPERL_COOKIE_DOMAIN</A> (see below).
+<DT><STRONG><A NAME="item_cookie_expires">cookie_expires</A></STRONG><DD>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_MAILDEBUG">EMBPERL_MAILDEBUG</A></H2>
+Same as <A href="Embperl.pod.3.html#EMBPERL_COOKIE_EXPIRES">EMBPERL_COOKIE_EXPIRES</A> (see below).
+
+<DT><STRONG><A NAME="item_errors">errors</A></STRONG><DD>
<P>
-(only 1.2.1 or above) Debugsetting for Net::SMTP. Default is 0.
+Takes a reference to an array. Upon return the array will contain a copy of
+all errormessages, as long as there are any.
+</DL>
<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_MAIL_ERRORS_TO">EMBPERL_MAIL_ERRORS_TO</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="Helper_functions_for_Execute">Helper functions for Execute</A></H2>
+<DL>
+<DT><STRONG><A NAME="item_HTML">HTML::Embperl::Init ($Logfile, $DebugDefault)</A></STRONG><DD>
<P>
-If set all errors will be send to the email adress given.
+This function can be used to setup the logfile path and (optional) a
+default value for the debugflags, which will be used in further calls to
+Execute. There will always be only one logfile, but you can use <STRONG>Init</STRONG>
+to change it at any time.
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COOKIE_NAME">EMBPERL_COOKIE_NAME</A></H2>
+<STRONG>NOTE:</STRONG> You do not need to call Init in version >= 0.27. The initialization of
+Embperl takes place automatically when it is loaded.
+
+<DT><STRONG><A NAME="item_HTML">HTML::Embperl::ScanEnvironement (\%params)</A></STRONG><DD>
<P>
-(only 1.2b4 or above) Set the name that Embperl uses when it sends the
-cookie with the session id. Default is EMBPERL_UID.
+Scans the <STRONG>%ENV</STRONG> and setups <STRONG>%params</STRONG> for use by <STRONG>Execute</STRONG>. All Embperl runtime configuration options are recognized, except
+EMBPERL_LOG.
+</DL>
<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COOKIE_DOMAIN">EMBPERL_COOKIE_DOMAIN</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EXAMPLES_for_Execute_">EXAMPLES for Execute:</A></H2>
<P>
-(only 1.2b4 or above) Set the domain that Embperl uses for the cookie with
-the session id. Default is none.
-
+<PRE> # Get source from /path/to/your.html and
+ # write output to /path/to/output'
+</PRE>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COOKIE_PATH">EMBPERL_COOKIE_PATH</A></H2>
+<PRE> HTML::Embperl::Execute ({ inputfile => '/path/to/your.html',
+ outputfile => '/path/to/output'}) ;
+</PRE>
<P>
-(only 1.2b4 or above) Set the path that Embperl uses for the cookie with
-the session id. Default is none.
-
+<PRE> # Get source from scalar and write output to stdout
+ # Don't forget to modify mtime if $src changes
+</PRE>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COOKIE_EXPIRES">EMBPERL_COOKIE_EXPIRES</A></H2>
+<PRE> $src = '<html><head><title>Page [+ $no +]</title></head>' ;
+</PRE>
<P>
-(only 1.2b4 or above) Set the expiration date that Embperl uses for the
-cookie with the session id. Default is none.
-
+<PRE> HTML::Embperl::Execute ({ inputfile => 'some name',
+ input => \$src,
+ mtime => 1 }) ;
+</PRE>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_SESSION_CLASSES">EMBPERL_SESSION_CLASSES</A></H2>
+<PRE> # Get source from scalar and write output to another scalar
+</PRE>
<P>
-Space separted list of object store and lock manager for Apache::Session
-(see <A href="Embperl.pod.6.html#Session_handling">Session handling</A>)
-
+<PRE> my $src = '<html><head><title>Page [+ $no +]</title></head>' ;
+ my $out ;
+</PRE>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_SESSION_ARGS">EMBPERL_SESSION_ARGS</A></H2>
+<PRE> HTML::Embperl::Execute ({ inputfile => 'another name',
+ input => \$src,
+ mtime => 1,
+ output => \$out }) ;
+</PRE>
<P>
-List of arguments for Apache::Session classes (see <A href="Embperl.pod.6.html#Session_handling">Session handling</A>) Example:
-
+<PRE> print $out ;
+</PRE>
<P>
-<PRE> PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=www Password=secret"
+<PRE> # Include a common header in an Embperl page,
+ # which is stored in /path/to/head.html
+
+ [- Execute ('/path/to/head.html') -]
+
</PRE>
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.1.html">PREV (Operating-Modes)</a>] [<a href="Embperl.pod.3.html">NEXT (SYNTAX)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.1.html">PREV (DESCRIPTION)</a>] [<a href="Embperl.pod.3.html">NEXT (Runtime configuration)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.12 +431 -366 modperl-site/embperl/Embperl.pod.3.html
Index: Embperl.pod.3.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.3.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- Embperl.pod.3.html 2000/02/11 22:34:16 1.11
+++ Embperl.pod.3.html 2000/02/20 20:29:32 1.12
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>SYNTAX</TITLE>
+<TITLE>Runtime configuration</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="SYNTAX">SYNTAX</a></strong></h1>
+<A NAME="Runtime_configuration">Runtime configuration</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,574 +16,639 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.2.html">PREV (Runtime configuration)</a>] [<a href="Embperl.pod.4.html">NEXT (Variable scope and cleanup)</a>] <br> <UL>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.2.html">PREV (Operating-Modes)</a>] [<a href="Embperl.pod.4.html">NEXT (SYNTAX)</a>] <br> <UL>
- <LI><A href="Embperl.pod.3.html#_Perl_code_">[+ Perl code +]</A>
- <LI><A href="Embperl.pod.3.html#_Perl_code_">[- Perl code -]</A>
- <LI><A href="Embperl.pod.3.html#_Perl_Code_">[! Perl Code !]</A>
- <LI><A href="Embperl.pod.3.html#_Perl_code_">[* Perl code *]</A>
- <LI><A href="Embperl.pod.3.html#_Some_Text_Comments_">[# Some Text #] (Comments)</A>
- <LI><A href="Embperl.pod.3.html#_Cmd_Arg_Meta_Commands_">[$ Cmd Arg $] (Meta-Commands)</A>
- <LI><A href="Embperl.pod.3.html#HTML_Tags">HTML Tags</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_FILESMATCH">EMBPERL_FILESMATCH</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_ALLOW_only_1_2b10_and_a">EMBPERL_ALLOW (only 1.2b10 and above)</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_PATH_1_3b1_and_above_">EMBPERL_PATH (1.3b1 and above)</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COMPARTMENT">EMBPERL_COMPARTMENT</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_ESCMODE">EMBPERL_ESCMODE</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_LOG">EMBPERL_LOG</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_PACKAGE">EMBPERL_PACKAGE</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_OPTIONS">EMBPERL_OPTIONS</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_INPUT_FUNC">EMBPERL_INPUT_FUNC</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_OUTPUT_FUNC">EMBPERL_OUTPUT_FUNC</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_MAILHOST">EMBPERL_MAILHOST</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_MAILFROM">EMBPERL_MAILFROM </A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_MAILDEBUG">EMBPERL_MAILDEBUG </A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_MAIL_ERRORS_TO">EMBPERL_MAIL_ERRORS_TO</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COOKIE_NAME">EMBPERL_COOKIE_NAME</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COOKIE_DOMAIN">EMBPERL_COOKIE_DOMAIN</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COOKIE_PATH">EMBPERL_COOKIE_PATH</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COOKIE_EXPIRES">EMBPERL_COOKIE_EXPIRES</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_SESSION_CLASSES">EMBPERL_SESSION_CLASSES</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_SESSION_ARGS">EMBPERL_SESSION_ARGS</A>
</UL>
<hr>
<P>
-Embperl understands two categories of commands. The first one are special
-Embperl commands, and the second category consists of some HTML tags which
-can trigger special processing. Embperl commands can span multiple lines
-and need not start or end at a line boundary.
+The runtime configuration is done by setting environment variables, either
+on the command line (when working offline) or in your web server's
+configuration file. Most HTTP servers understand
<P>
-Before the special Embperl commands are processed, and for the VALUE
-attribute of the INPUT tag (see below), all HTML tags are removed and
-special HTML characters are translated to their ASCII values (e.g.,
-`&lt;' is translated to `<'). You can avoid this behavior by
-preceding the special character or HTML tag with a backslash. This is done
-in case your favorite (WYSIWYG) HTML editor inserts tags like line breaks
-or formatting into your Embperl commands where you don't want them.
+SetEnv <var> <value>
<P>
-<STRONG>VERY IMPORTANT NOTE:</STRONG> If you do use an ASCII editor to write your HTML documents, you should set
-the option <STRONG>optRawInput</STRONG> so that Embperl does not preprocess your source. You can also HTML-escape
-your code (i.e. write `&lt;' instead of `<'), to avoid ambiguity. In
-most cases it will also work without the optRawInput and HTML-escaping, but
-in some cases Embperl will detect an HTML tag were there isn't one.
+If you are using Apache and mod_perl you can use
<P>
-<STRONG>If you have any trouble with your code, especially with HTML tags or filehandles
-in your Perl code, be sure to understand input- and output- escaping and
-unescaping. Read the section
-<A href="Embperl.pod.10.html#Inside_Embperl_How_the_embedde">"Inside Embperl"</A>
-to see what's going on!!</STRONG>
+PerlSetEnv <var> <value>
-
-
<P>
-All Embperl commands start with a `[' and end with a `]'. To get a real `['
-you must enter `[['.
+The advantage of PerlSetEnv over SetEnv is that it can be used on a per
+directory/virtual host basis.
<P>
-Embperl does not use SGML comments (i.e., <! ... !> or similar things) because some HTML editors can't create them,
-or it's much more complicated. Since every HTML editor takes (or <STRONG>should</STRONG> take) `[' and `]' as normal text, there should be no problem.
-
-<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Perl_code_">[+ Perl code +]</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_FILESMATCH">EMBPERL_FILESMATCH</A></H2>
<P>
-Replace the command with the result you get from evaluating the Perl code.
-The Perl code can be anything which can be used as an argument to a Perl
-eval statement. (See <A href="Embperl.pod.7.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> below for restrictions.) Examples:
+If specified, only files which match the given <STRONG>perl regular expression</STRONG> will be processed by Embperl, all other files will be handled by the
+standard Apache handler. This can be useful if you have Embperl documents
+and non Embperl documents (e.g. gifs) cohabitating in the same directory.
+EMBPERL_FILESMATCH works only under mod_perl.
-<P>
-<PRE> [+ $a +] Replaces the [+ $a +] with the content of
- the variable $a
-</PRE>
<P>
-<PRE> [+ $a+1 +] (Any expression can be used)
+<PRE> Example:
+ # Only files which end with .htm will processed by Embperl
+ PerlSetEnv EMBPERL_FILESMATCH \.htm$
</PRE>
<P>
-<PRE> [+ $x[$i] +] (Arrays, hashes, and more complex
- expressions work)
-</PRE>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_ALLOW_only_1_2b10_and_a">EMBPERL_ALLOW (only 1.2b10 and above)</A></H2>
<P>
-<CODE>NOTE:</CODE> Whitespace is ignored. The output will be automatically HTML-escaped (e.g.,
-`<' is translated to `&lt;') depending on the value of the variables <A href="Embperl.pod.5.html#item__escmode">$escmode</A>. You do not have to worry about it.
+If specified, only files which match the given <STRONG>perl regular expression</STRONG> will be processed by Embperl, all other files will return FORBIDDEN.
+Especialy in a CGI environenemt this can be usefull to make a server more
+secure.
<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Perl_code_">[- Perl code -]</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_PATH_1_3b1_and_above_">EMBPERL_PATH (1.3b1 and above)</A></H2>
<P>
-Executes the Perl code, but deletes the whole command from the HTML output.
+Can contain a colon separated file search path. When a file is processed
+and the filename does not contain a path, <EM>Embperl</EM> searches all the specified directories for that file.
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COMPARTMENT">EMBPERL_COMPARTMENT</A></H2>
<P>
-Examples:
+Gives the name of the compartment from which to take the opcode mask. (See
+the chapter about <A href="Embperl.pod.8.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> for more details.)
<P>
-<PRE> [- $a=1 -] Set the variable $a to one.
- No output will be generated.
-</PRE>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_ESCMODE">EMBPERL_ESCMODE</A></H2>
<P>
-<PRE> [- use SomeModule ; -] You can use other modules. NOTE the semikolon!
-</PRE>
+Specifies the initial value for <A href="Embperl.pod.6.html#_escmode">$escmode</A> (see below).
+
<P>
-<PRE> [- $i=0; while ($i<5) {$i++} -] Even more complex
- statements or multiple
- statements are possible.
-</PRE>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_LOG">EMBPERL_LOG</A></H2>
<P>
-<CODE>NOTE:</CODE> Statements like if, while, for, etc., must be contained in a single Embperl
-command. You cannot have the if in one command block and the terminating
-`}' or else in another.
+Gives the location of the log file. This will contain information about
+what Embperl is doing. How much information depends on the debug settings
+(see <A href="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> below). The log output is intended to show what your embedded Perl code is
+doing and to help debug it. The default is
+<STRONG>/tmp/embperl.log</STRONG>.
<P>
-<CODE>NOTE:</CODE> To define subroutines, use <A href="Embperl.pod.3.html#_Perl_Code_">[! Perl Code !]</A> (see below) instead of [- ... -] to avoid recompilation of the subroutine
-on every request.
+<STRONG>NOTE:</STRONG> When running under mod_perl you need to use <STRONG>PerlSetEnv</STRONG> for setting the logfile path, and mod_perl >= 1.07_03 if you load
+Embperl at server startup (with PerlScript or PerlModule).
<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Perl_Code_">[! Perl Code !]</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_PACKAGE">EMBPERL_PACKAGE</A></H2>
<P>
-Same as [- Perl Code -] with the exception that the code is only executed
-at the first request. This could be used to define subroutines, or do
-one-time initialization.
+The name of the package where your code will be executed. By default,
+Embperl generates a unique package name for every file. This ensures that
+variables and functions from one file can not affect those from another
+file. (Any package's variables will still be accessible with explicit
+package names.)
<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Perl_code_">[* Perl code *]</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A></H2>
<P>
-(only version 1.2b2 or higher) <STRONG>EXPERIMENTAL!</STRONG>
+Gives a virtual location where you can access the Embperl logfile with a
+browser. This feature is disabled (default) if EMBPERL_VIRTLOG is not
+specified. See also <A href="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> and dbgLogLink for an Example how to set it up in your srm.conf.
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_OPTIONS">EMBPERL_OPTIONS</A></H2>
+<P>
+This bitmask specifies some options for the execution of Embperl. To
+specify multiple options, simply add the values together.
+<DL>
+<DT><STRONG><A NAME="item_optDisableVarCleanup">optDisableVarCleanup = 1</A></STRONG><DD>
+<P>
+Disables the automatic cleanup of variables at the end of each request.
+<DT><STRONG><A NAME="item_optDisableEmbperlErrorPage">optDisableEmbperlErrorPage = 2</A></STRONG><DD>
<P>
-This is similar to [- Perl Code -], the main difference is, while [- Perl
-Code -], has always it's own scope, all [* Perl code *] blocks runs in the
-same scope. This gives you the possibilty to define ``local'' variables
-with a scope of the whole page. Normaly you don't need to use local,
-because Embperl takes care of separate namespaces of different documents
-and cleanup after the request is finished, but in special cases it's
-necessary. For example if you want recursivly call an Embperl document via
-Execute.
+Tells Embperl to not send its own errorpage in case of failure, instead
+shows as much of the page as possible. Errors are only logged to the log
+file. Without this option, Embperl sends its own error page, showing all
+the errors which have occurred. If you have dbgLogLink enabled, every error
+will be a link to the corresponding location in the log file. This option
+has no effect if optReturnError is set.
+<DT><STRONG><A NAME="item_optReturnError">optReturnError = 262144</A></STRONG><DD>
<P>
-There is a second reason to use the [* Perl code *] instead of the [- Perl
-Code -]. If you like to use perl's control structures. Perl's if, while,
-for etc. can <STRONG>not</STRONG> span mulitple [- Perl Code -] blocks, but it can span multiple [* Perl Code
-*].
+With this option set Embperl sends no output in case of an error, instead
+it returns the error back to Apache or the calling programm. When running
+under mod_perl this gives you the chance to use the Apache <EM>ErrorDocument</EM>
+directive to show a custom error-document.
+<DT><STRONG><A NAME="item_optSafeNamespace">optSafeNamespace = 4</A></STRONG><DD>
<P>
-<PRE> Example:
-</PRE>
+Tells Embperl to execute the embedded code in a safe namespace so the code
+cannot access data or code in any other package. (See the chapter about <A href="Embperl.pod.8.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> below for more details.)
+
+<DT><STRONG><A NAME="item_optOpcodeMask">optOpcodeMask = 8</A></STRONG><DD>
<P>
-<PRE> [* foreach $i (1..10) { *]
-
- [- $a = $i + 5 -]
- loop count + 5 = [+ $a +] <br>
-</PRE>
+Tells Embperl to apply an operator mask. This gives you the chance to
+disallow special (unsafe) opcodes. (See the Chapter about
+<A href="Embperl.pod.8.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A>
+below for more details.)
+
+<DT><STRONG><A NAME="item_optRawInput">optRawInput = 16</A></STRONG><DD>
<P>
-<PRE> [* } *]
-</PRE>
+Causes Embperl not to pre-process the source for a Perl expression. (The
+only exception is that carriage returns will be removed, as Perl does not
+like them.) This option should be set when you are writing your code with
+an ASCII editor.
+
<P>
-<PRE> The following B<won't> work:
-</PRE>
+If you are using a WYSIWYG editor which inserts unwanted HTML tags in your
+Perl expressions and escapes special charcaters automatically (e.g., `<'
+appears as `&lt;' in the source), you should not set this option.
+Embperl will automatically convert the HTML input back to the Perl
+expressions as you wrote them.
+
+<DT><STRONG><A NAME="item_optEarlyHttpHeader">optEarlyHttpHeader = 64</A></STRONG><DD>
<P>
-<PRE> [- foreach $i (1..10) { -]
- some text here <br>
- [- } -]
-</PRE>
+Normally, HTTP headers are sent after a request is finished without error.
+This gives you the chance to set arbitrary HTTP headers within the page,
+and gives Embperl the chance to calculate the content length. Also Embperl
+watches out for errors and sends an errorpage instead of the document if
+something goes wrong. To do this, all the output is kept in memory until
+the whole request is processed, then the HTTP headers are sent, and then
+the document. This flag will cause the HTTP headers to be sent before the
+script is processed, and the script's output will be sent directly.
+
+<DT><STRONG><A NAME="item_optDisableChdir">optDisableChdir = 128</A></STRONG><DD>
<P>
-The same can be done with Embperl <A href="Embperl.pod.3.html#_Cmd_Arg_Meta_Commands_">meta commands</A> (see below)
+Without this option, Embperl changes the currect directory to the one where
+the script resides. This gives you the chance to use relative pathnames.
+Since directory-changing takes up some millisecs, you can disable it with
+this option if you don't need it.
+<DT><STRONG><A NAME="item_optDisableFormData">optDisableFormData = 256</A></STRONG><DD>
<P>
-<PRE> [$ foreach $i (1..10) $]
-
- [- $a = $i + 5 -]
- loop count + 5 = [+ $a +] <br>
-</PRE>
+This option disables the setup of <CODE>%fdat</CODE> and @ffld. Embperl will not do anything with the posted form data.
+
+<DT><STRONG><A NAME="item_optDisableHtmlScan">optDisableHtmlScan = 512</A></STRONG><DD>
<P>
-<PRE> [$ endforeach $]
-</PRE>
+When set, this option disables the scanning of <STRONG>all</STRONG> html-tags. Embperl will only look for [+/-/!/$ ... $/!/-/+]. This will
+disable dynamic tables, processing of the input data and so on.
+
+<DT><STRONG><A NAME="item_optDisableInputScan">optDisableInputScan = 1024</A></STRONG><DD>
<P>
-<STRONG>NOTE 1:</STRONG> [* ... *] blocks _must_ always end with a <STRONG>;</STRONG>,<STRONG>{</STRONG> or <STRONG>}</STRONG>
+Disables processing of all input-related tags.
+(<INPUT><TEXTAREA><OPTION>)
+<DT><STRONG><A NAME="item_optDisableTableScan">optDisableTableScan = 2048</A></STRONG><DD>
+<P>
+Disables processing of all table-related tags.
+(<TABLE><TH><TR><TD><MENU><OL><SELECT><UL>)
+<DT><STRONG><A NAME="item_optDisableMetaScan">optDisableMetaScan = 4096</A></STRONG><DD>
<P>
-<STRONG>NOTE 2:</STRONG> [* ... *] cannot apear inside a html tag that is interpreted by Embperl
-(unless you disable the interpretation of such tags like table, input etc.)
+Disables processing of all meta tags. (<META HTTP-EQUIV>)
+<DT><STRONG><A NAME="item_optAllFormData">optAllFormData = 8192</A></STRONG><DD>
<P>
-<STRONG>NOTE 3:</STRONG> Since the execution of [- ... -] and metacommands is controlled by Embperl,
-there is a much better debugging output in the logfile for this two ones.
-Also no restriction where they can be used apply to meta-commands. You can
-use them anywhere even inside of html tags that are interpreted by Embperl.
+This option will cause Embperl to insert all formfields in
+<CODE>%fdat</CODE> and @ffld, even if they are empty. Empty formfields will be inserted with an
+empty string. Without this option empty formfields will not be insert in
+<CODE>%fdat</CODE> and @ffld.
+<DT><STRONG><A NAME="item_optRedirectStdout">optRedirectStdout = 16384</A></STRONG><DD>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Some_Text_Comments_">[# Some Text #] (Comments)</A></H2>
+Redirects STDOUT to the Embperl output stream before every request and
+resets it afterwards. If set, you can use a normal Perl <STRONG>print</STRONG> inside any Perl block to output data. Without this option you can only
+output data by using the [+ ... +] block, or printing to the filehandle <STRONG>OUT</STRONG>.
+
+<DT><STRONG><A NAME="item_optUndefToEmptyValue">optUndefToEmptyValue = 32768</A></STRONG><DD>
+<P>
+Normally if there is no value in <CODE>%fdat</CODE> for a specific input
+field, Embperl will leave it untouched. When this option is set, Embperl
+will handle the field as if an empty string was stored in
+<CODE>%fdat</CODE> for the field.
+
+<DT><STRONG><A NAME="item_optNoHiddenEmptyValue">optNoHiddenEmptyValue = 65536 (only 1.2b2 and above)</A></STRONG><DD>
+<P>
+Normally, if there is a value defined in <CODE>%fdat</CODE> for a specific
+input field, Embperl will output a hidden input element for it when you use <STRONG>hidden</STRONG>. When this option is set, Embperl will not output a hidden input element
+for this field when the value is a blank string.
+
+<DT><STRONG><A NAME="item_optAllowZeroFilesize">optAllowZeroFilesize = 131072 (only 1.2b2 and above)</A></STRONG><DD>
<P>
-(only version 1.2b2 or higher)
+Normaly Embperl reports NOT_FOUND (404) if a file of length zero is
+requested. With this option set Embperl will return an empty document.
+<DT><STRONG><A NAME="item_optKeepSrcInMemory">optKeepSrcInMemory = 524288 (only 1.2b5 and above)</A></STRONG><DD>
<P>
-This is a comment block. Everything between the [# and the #] will be
-removed from the output.
+Tells Embperl to keep the source file in memory and not reload it on every
+request. (The precompiled Perlcode is always kept in memory, regardless of
+this flag)
+<DT><STRONG><A NAME="item_optKeepSpaces">optKeepSpaces = 1048576 (only 1.2b5 and above) = 0x100000,</A></STRONG><DD>
<P>
-<STRONG>NOTE 1:</STRONG> The [* ... *] blocks are interpreted before the comment block, so they are
-executed also inside a comment.
+Disable the removing of spaces and empty lines from the output. This is
+usefull for other sources then HTML.
+<DT><STRONG><A NAME="item_optOpenLogEarly">optOpenLogEarly = 2097152 (only 1.2b5 and above)</A></STRONG><DD>
<P>
-<STRONG>NOTE 2:</STRONG> Everything (except [* ... *]) is really removed from the source, so you can
-also use the [# ... #] block to take a part out of your document.
+This option causeses Embperl to open the logfile as soon as it is loaded
+into memory. You can use this when you load Embperl via PerlModule under
+Apache, to open the log as root instead of the non-privileged user Apache
+runs as. =item optUncloseWarn = 4194304 (only 1.2b6 and above)
<P>
+Disable the warnings about unclosed <CODE>if</CODE>, <CODE>while</CODE>, <CODE>table</CODE> etc. at the end of the file.
+
+</DL>
+<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Cmd_Arg_Meta_Commands_">[$ Cmd Arg $] (Meta-Commands)</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_DEBUG">EMBPERL_DEBUG</A></H2>
<P>
-Execute an Embperl metacommand. <STRONG>Cmd</STRONG> can be one of the following. (<STRONG>Arg</STRONG> varies depending on <Cmd>).
+This is a bitmask which specifies what should be written to the log. To
+specify multiple debugflags, simply add the values together. The following
+values are defined:
<DL>
-<DT><STRONG><A NAME="item_if">if, elsif, else, endif</A></STRONG><DD>
+<DT><STRONG><A NAME="item_dbgStd">dbgStd = 1</A></STRONG><DD>
<P>
-Everything following the <STRONG>if</STRONG> metacommand until the <STRONG>else</STRONG>,
-<STRONG>elsif</STRONG>, or <STRONG>endif</STRONG> is only output if the Perl expression given in
-<STRONG>Arg</STRONG> is true. <STRONG>else</STRONG> and <STRONG>elsif</STRONG> work similarly.
+Show minimum information.
+<DT><STRONG><A NAME="item_dbgMem">dbgMem = 2</A></STRONG><DD>
<P>
-Example:
+Show memory and scalar value allocation.
+<DT><STRONG><A NAME="item_dbgEval">dbgEval = 4</A></STRONG><DD>
<P>
-<PRE> [$ if $ENV{REQUEST_METHOD} eq 'GET' $]
- Method was GET<BR>
- [$ else $]
- Method other than GET used<BR>
- [$ endif $]
-</PRE>
-<P>
-This will send one of the two sentences to the client, depending on the
-request method used to retrieve the document.
+Show arguments to and results of evals.
-<DT><STRONG><A NAME="item_while">while, endwhile</A></STRONG><DD>
+<DT><STRONG><A NAME="item_dbgCmd">dbgCmd = 8</A></STRONG><DD>
<P>
-Executes a loop until the <STRONG>Arg</STRONG> given to <STRONG>while</STRONG> is false.
+Show metacommands and HTML tags which are processed.
+<DT><STRONG><A NAME="item_dbgEnv">dbgEnv = 16,</A></STRONG><DD>
<P>
-Example: (see eg/x/loop.htm)
+List every request's environment variables.
+<DT><STRONG><A NAME="item_dbgForm">dbgForm = 32</A></STRONG><DD>
<P>
-<PRE> [- $i = 0; @k = keys %ENV -]
- [$ while ($i &lt; $#k) $]
- [+ $k[$i] +] = [+ $ENV{$k[$i]} +]<BR>
- [- $i++ -]
- [$ endwhile $]
-</PRE>
+Lists posted form data.
+
+<DT><STRONG><A NAME="item_dbgTab">dbgTab = 64</A></STRONG><DD>
<P>
-This will send a list of all environment variables to the client.
+Show processing of dynamic tables.
+<DT><STRONG><A NAME="item_dbgInput">dbgInput = 128</A></STRONG><DD>
<P>
-NOTE: The `&lt;' is translated to `<' before calling Perl eval,
-unless optRawInput is set.
+Show processing of HTML input tags.
-<DT><STRONG><A NAME="item_do">do, until</A></STRONG><DD>
+<DT><STRONG><A NAME="item_dbgFlushOutput">dbgFlushOutput = 256</A></STRONG><DD>
<P>
-Executes a loop until the <STRONG>Arg</STRONG> given to <STRONG>until</STRONG> is true.
+Flush Embperl's output after every write. This should only be set to help
+debug Embperl crashes, as it drastically slows down Embperl's operation.
+<DT><STRONG><A NAME="item_dbgFlushLog">dbgFlushLog = 512</A></STRONG><DD>
<P>
-<PRE> Example:
-</PRE>
+Flush Embperl's logfile output after every write. This should only be set
+to help debug Embperl crashes, as it drastically slows down Embperl's
+operation.
+
+<DT><STRONG><A NAME="item_dbgAllCmds">dbgAllCmds = 1024</A></STRONG><DD>
<P>
-<PRE> [- $i = 0 -]
- [$ do $]
- [+ $i++ +] <BR>
- [$ until $i > 10 $]
-</PRE>
-<DT><STRONG><A NAME="item_foreach">foreach, endforeach</A></STRONG><DD>
+Logs all commands and HTML tags, whether or not they are really excuted or
+not. (It logs a `+' or `-' to tell you if they are executed.)
+
+<DT><STRONG><A NAME="item_dbgSource">dbgSource = 2048</A></STRONG><DD>
<P>
-Executes a loop for each element of the second <STRONG>Arg</STRONG>, setting the first <STRONG>Arg</STRONG> accordingly.
+Logs the next piece of the HTML source to be processed. (NOTE: This
+generates a lot of output!)
+<DT><STRONG><A NAME="item_dbgFunc">dbgFunc = 4096</A></STRONG><DD>
<P>
-<PRE> Example:
-</PRE>
+This is only anvailable when Embperl is compiled with -DEPDEBUGALL, and is
+normally only used for debugging Embperl itself. Records all function
+entries to the logfile.
+
+<DT><STRONG><A NAME="item_dbgLogLink">dbgLogLink = 8192</A></STRONG><DD>
<P>
-<PRE> [- @arr = (1, 3, 5) -]
- [$ foreach $v @arr $]
- [+ $v +] <BR>
- [$ endforeach $]
-</PRE>
-<DT><STRONG><A NAME="item_hidden">hidden</A></STRONG><DD>
-<P>
-<STRONG>Arg</STRONG> consists of zero, one or two names of hashes (with or without the leading
-%) and an optional array as third parameter. The
-<STRONG>hidden</STRONG> metacommand will generate hidden fields for all data contained in the first
-hash but not in the second hash. The default used for the first hash is <CODE>%fdat</CODE>, <CODE>%idat</CODE> is used for the second.
-
-<P>
-If the third parameter is specified, the fields are written in the order
-they appear in this array. That is, all keys of the first hash must be
-properly sorted in this array. This is intended for situations where you
-want to pass data from one form to the next, for example, two forms which
-should be filled in one after the other. (Examples might be an input form
-and a second form to review and accept the input, or a Windows-style
-``wizard''). Here you can pass along data from previous forms in hidden
-fields. (See eg/x/neu.htm for an example.) If you use just the 'hidden'
-command without parameters, it simply generates hidden fields for all form
-fields submitted to this document which aren't already contained in another
-input field.
+Inserts a link at the top of each page which can be used to view the log
+for the current HTML file. See also <A href="Embperl.pod.3.html#EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A>.
<P>
Example:
<P>
-<PRE> <FORM ACTION="inhalt.htm" METHOD="GET">
- <INPUT TYPE="TEXT" NAME="field1">
- [$ hidden $]
- </FORM>
+<PRE> SetEnv EMBPERL_DEBUG 10477
+ SetEnv EMBPERL_VIRTLOG /embperl/log
</PRE>
<P>
-If you request this with <A
-HREF="http://host/doc.htm?field1=A&field2=B&field3=C">http://host/doc.htm?field1=A&field2=B&field3=C</A>
+<PRE> <Location /embperl/log>
+ SetHandler perl-script
+ PerlHandler HTML::Embperl
+ Options ExecCGI
+ </Location>
+</PRE>
+<DT><STRONG><A NAME="item_dbgDefEval">dbgDefEval = 16384</A></STRONG><DD>
+<P>
+Shows every time new Perl code is compiled.
+<DT><STRONG><A NAME="item_dbgCacheDisable">dbgCacheDisable = 32768</A></STRONG><DD>
+<P>
+Disables the use of the p-code cache. All Perl code is recompiled every
+time. (This should not be used in normal operation as it slows down Embperl
+dramatically.) This option is only here for debugging Embperl's cache
+handling. There is no guarantee that Embperl behaves the same with and
+without cache (actually is does not!)
+<DT><STRONG><A NAME="item_dbgHeadersIn">dbgHeadersIn = 262144</A></STRONG><DD>
<P>
-the output will be
+Log all HTTP headers which are sent from the browser.
+<DT><STRONG><A NAME="item_dbgShowCleanup">dbgShowCleanup = 524288</A></STRONG><DD>
<P>
-<PRE> <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>
-</PRE>
+Show every variable which is undef'd at the end of the request. For scalar
+variables, the value before undef'ing is logged.
+
+<DT><STRONG><A NAME="item_dbgProfile">dbgProfile = 1048576 (only 1.2b4 and above)</A></STRONG><DD>
<P>
-<CODE>NOTE:</CODE> This should only be used for a small amount of data, since the hidden
-fields are sent to the browser, which sends it back with the next request.
-If you have a large amount of data, store it in a file with a unique name
-and send only the filename in a hidden field. Be aware of the fact that the
-data can be change by the browser if the user doesn't behave exactly as you
-expect. Users have a nasty habit of doing this all of the time. Your
-program should be able to handle such situations properly.
+When set every source line in the log file will also display the time until
+request was started. (<STRONG>dbgSource</STRONG> must also be set)
-<DT><STRONG><A NAME="item_var">var</A></STRONG><DD>
+<DT><STRONG><A NAME="item_dbgSession">dbgSession = 2097152 (only 1.2b4 and above)</A></STRONG><DD>
<P>
-The var command declares one or more variables for use within this Embperl
-document and sets the <STRONG>strict</STRONG> pragma. The variable names must be supplied as space-separated list.
+Enables logging of session transactions.
+<DT><STRONG><A NAME="item_dbgImport">dbgImport = 4194304 (only 1.2b5 and above)</A></STRONG><DD>
<P>
-Example: [$var <CODE>$a</CODE> <CODE>%b</CODE> <CODE>@c</CODE> $]
+Show how subroutines are imported in other namesapces
+</DL>
<P>
-This is the same as writing the following in normal Perl code:
+A good value to start is <CODE>2285</CODE> or <CODE>10477</CODE> if you want to view the logfile with your browser. (Don't forget to set
+EMBPERL_VIRTLOG.) If Embperl crashes, add <CODE>512</CODE> so the logfile is flushed after every line is written and you can see where
+Embperl is when it crashes.
<P>
-<PRE> use strict ;
- use vars qw($a %b @c) ;
-</PRE>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_INPUT_FUNC">EMBPERL_INPUT_FUNC</A></H2>
<P>
-NOTE 1: `use strict' within an Embperl document will only apply to the
-block in which it occurs.
+This directive gives you the possiblity to specify a non-standard way of
+fetching input. Normally, Embperl reads its input (source) from a file (or
+gets it from a scalar if you use <CODE>Execute</CODE>). Here, you can give the name of a Perl function which is called instead
+of reading the input from a file. The function must look like the
+following:
-<DT><STRONG><A NAME="item_sub">sub</A></STRONG><DD>
<P>
-(Only Embperl 1.2b5 and above)
+<PRE> InputFunc ($r, $in, $cacheargs, additional parameters...) ;
+</PRE>
+<DL>
+<DT><STRONG><A NAME="item__r">$r</A></STRONG><DD>
+<P>
+Apache Request Record (see <STRONG>perldoc Apache</STRONG> for details)
+<DT><STRONG><A NAME="item__in">$in</A></STRONG><DD>
<P>
-Defines a Embperl subroutine. Example:
+a reference to a scalar, to which the input should be returned.
<P>
-<PRE> [$ sub foo $]
- <p> Here we do something </p>
- [$ endsub $]
+<PRE> Example:
</PRE>
<P>
-You can call this subroutine either as a normal Perl subroutine
+<PRE> open F, "filename" ;
+ local $\ = undef ;
+ $$in = <F> ;
+ close F ;
+</PRE>
+<DT><STRONG><A NAME="item__cacheargs">$cacheargs</A></STRONG><DD>
+<P>
+a reference to a scalar, to which the modification time should be returned,
+alternativ (1.2.1 and up) you can return a reference to a hash with the
+elements <A href="Embperl.pod.2.html#item_mtime">mtime</A> and <A href="Embperl.pod.2.html#item_inputfile">inputfile</A>
+with are used to correcly cache the precompiled Perlcode.
+<P>
+<PRE> Example:
+</PRE>
<P>
-<PRE> [- foo -]
+<PRE> $$cacheargs = -M "filename" ;
</PRE>
<P>
-or via the HTML::Embperl::Execute function.
-
+<PRE> or
+</PRE>
<P>
-<PRE> [- Execute ('#foo') # short form -]
- [- Execute ({ sub => 'foo'}) # long form -]
+<PRE> $$cacheargs = { mtime => -M "filename", inputfile => "filename" } ;
</PRE>
+</DL>
<P>
-The difference is that the Execute function will reset the internal states
-of Embperl like they were before the subrountine call, when the subroutine
-returns. Also Execute could handle recursive call, which currently not work
-when calling it as a Perl subroutine.
+You can give <STRONG>additional parameters</STRONG> (which must be comma-separated) to <STRONG>EMBPERL_INPUT_FUNC</STRONG>
+which will then pass them as a string.
<P>
-You may also pass Parameters to the subroutine:
-
+<PRE> Example:
+</PRE>
+<P>
+<PRE> PerlSetEnv EMBPERL_INPUT_FUNC "InputFunc, foo, bar"
+</PRE>
<P>
-<PRE> [$ sub foo $]
- [- $p = shift -]
- <p> Here we show the first parameter [+ $p +]</p>
- [$ endsub $]
+<PRE> will call
</PRE>
<P>
-<PRE>
- [- foo ('value') -]
+<PRE> InputFunc ($r, $in, $mtime, 'foo', 'bar') ;
</PRE>
<P>
-If you have a couple of commonly used subroutines you can define then in
-one file and import them into the modules where they are neccesary:
+<PRE> to get the input.
+</PRE>
+<P>
+<STRONG>EXAMPLE for an input function which does just the same as Embperl</STRONG>
+
+
<P>
-<PRE> [- Execute ({ inputfile => 'mylib.htm', import => 1 }) -]
+<PRE> sub Input
</PRE>
<P>
-This will import all subroutines from the file <EM>mylib.htm</EM> into the current page where they could call just as a normal Perl
-subroutine.
+<PRE> {
+ my ($r, $in, $mtime) = @_ ;
+</PRE>
+<P>
+<PRE> open F, $r -> filename or return NOT_FOUND ;
+ local $\ = undef ;
+ $$in = <F> ;
+ close F ;
+</PRE>
+<P>
+<PRE> $$mtime = -M $r -> filename ;
+
+ return 0 ;
+ }
+</PRE>
+<P>
+See also <A href="Embperl.pod.10.html#ProxyInput_r_in_mtime_sr">ProxyInput</A> below, for an input function which comes with Embperl.
-</DL>
+<P>
+NOTE: There are also two modules (<EM>HTML::EmbperlChain</EM> and <EM>Apache::EmbperlFilter</EM>) which provides you with the possibility to chain <EM>Embperl</EM> and other modules together.
+
<P>
<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="HTML_Tags">HTML Tags</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_OUTPUT_FUNC">EMBPERL_OUTPUT_FUNC</A></H2>
<P>
-Embperl recognizes the following HTML tags specially. All others are simply
-passed through, as long as they are not part of a Embperl command.
+This directive allows you to specify a non-standard way of dealing with
+output. Normally, Embperl sends its output (source) to a file/the browser
+(or to a scalar if you use <CODE>Execute</CODE>). Here, you can give the name of a Perl function which is called instead
+of sending the output to a file/the browser. The function must look like
+the following:
+<P>
+<PRE> OutputFunc ($r, $out, additional parameters...) ;
+</PRE>
<DL>
-<DT><STRONG><A NAME="item_TABLE">TABLE, /TABLE, TR, /TR</A></STRONG><DD>
+<DT><STRONG>$r</STRONG><DD>
<P>
-Embperl can generate dynamic tables (one- or two-dimensional). You only
-need to specify one row or column.
+Apache Request Record (see <STRONG>perldoc Apache</STRONG> for details)
+<DT><STRONG><A NAME="item__out">$out</A></STRONG><DD>
<P>
-Embperl generates as many rows or columns as necessary. This is done by
-using the magic variables $row, $col, and $cnt. If you don't use
-$row/$col/$cnt within a table, Embperl does nothing and simply passes the
-table through.
+a reference to a scalar, which contains the output from Embperl
+</DL>
<P>
-Embperl checks if any of $row, $col, or <CODE>$cnt</CODE> is used. Embperl
-repeats all text between <table> and </table>, as long the
-expressions in which <CODE>$row</CODE> or <CODE>$cnt</CODE> occurs is/are
-defined.
+You can give <STRONG>additional parameters</STRONG> (which must be comma-separated) to <STRONG>EMBPERL_OUTPUT_FUNC</STRONG>, which will then pass them as a string.
<P>
-Embperl repeats all text between <tr> and </tr>, as long the
-expressions in which <CODE>$col</CODE> or <CODE>$cnt</CODE> occurs is/are
-defined.
-
+<PRE> Example:
+</PRE>
<P>
-See also <A href="Embperl.pod.5.html#_tabmode">$tabmode</A> (below) for end-of-table criteria.
-
+<PRE> PerlSetEnv EMBPERL_OUTPUT_FUNC "OutputFunc, foo, bar"
+</PRE>
<P>
-Examples: (see eg/x/table.htm for more examples)
-
+<PRE> will call
+</PRE>
<P>
-<PRE> [- @k = keys %ENV -]
- <TABLE>
- <TR>
- <TD>[+ $i=$row +]</TD>
- <TD>[+ $k[$row] +]</TD>
- <TD>[+ $ENV{$k[$i]} +]</TD>
- </TR>
- </TABLE>
+<PRE> OutputFunc ($r, $out, 'foo', 'bar') ;
</PRE>
<P>
-This will show all entries in array <CODE>@k</CODE> (which contains the
-keys from %ENV), so the whole environment is displayed (as in the <STRONG>while</STRONG>
-example), with the first column containing the zero-based index, the second
-containing the content of the variable name, and the third the environment
-variable's value.
-
+<PRE> for output.
+</PRE>
<P>
-This could be used to display the result of a database query if you have
-the result in an array. You may provide as many columns as you need. It is
-also possible to call a 'fetch' subroutine in each table row.
+<STRONG>EXAMPLE for an ouput function which does just the same as Embperl</STRONG>
-<DT><STRONG><A NAME="item_TH">TH, /TH</A></STRONG><DD>
-<P>
-The <TH> tag is interpreted as a table heading. If the whole row is
-made up of <TH> </TH> instead of <TD> </TD>, it is
-treated as a column heading. Everything else will be treated as row
-headings in the future, but are not now: everything else is ignored in the
-current version.
-<DT><STRONG><A NAME="item_DIR">DIR, MENU, OL, UL, DL, SELECT, /DIR, /MENU,
-/OL, /UL, /DL, /SELECT</A></STRONG><DD>
-<P>
-Lists and dropdowns or list boxes are treated exactly as one- dimensional
-tables. Only <A href=".html#_row">$row</A>, <A href=".html#_maxrow">$maxrow</A>, <A href=".html#_col">$col</A>, <A href=".html#_maxcol">$maxcol</A> and <A href="Embperl.pod.5.html#_tabmode">$tabmode</A>
-are honored. <CODE>$col</CODE> and <CODE>$maxcol</CODE> are ignored. See
-eg/x/lists.htm for an example.
-<DT><STRONG><A NAME="item_OPTION">OPTION</A></STRONG><DD>
<P>
-Embperl checks if there is a value from the form data for a specific option
-in a menu. If so, this option will be pre-selected.
-
+<PRE> sub Output
+</PRE>
<P>
-Example:
-
+<PRE> {
+ my ($r, $out) = @_ ;
+</PRE>
<P>
-<FORM METHOD=``POST''> <P>Select Tag</P>
-
+<PRE> $r -> send_http_header ;
+</PRE>
<P>
-<PRE> If you request this document with list.htm?SEL1=x
- you can specify that the element which has a value
- of x is initially selected
+<PRE> $r -> print ($$out) ;
</PRE>
<P>
-<PRE> <P><SELECT NAME="SEL1">
- <OPTION VALUE="[+ $v[$row] +]">
- [+ $k[$row] +]
- </OPTION>
- </SELECT></P>
-</FORM>
+<PRE> return 0 ;
+ }
</PRE>
-<DT><STRONG><A NAME="item_INPUT">INPUT</A></STRONG><DD>
<P>
-The INPUT tag interacts with the hashes <CODE>%idat</CODE> und <CODE>%fdat</CODE>. If the input tag has no value, and a key exists with the same text as the
-NAME attribute of the input tag, Embperl will generate a VALUE attribute
-with the corresponding value of the hash key. All values of <INPUT> tags are stored in the hash <CODE>%idat</CODE>, with NAME as the hash key and VALUE as the hash value. Special processing
-is done for TYPE=RADIO and TYPE=CHECKBOX. If the VALUE attribute contains
-the same text as the value of the hash the CHECKED attribute is inserted,
-else it is removed.
+See also <A href="Embperl.pod.10.html#LogOutput_r_out_basepath_">LogOutput</A> below, for an output function which comes with Embperl.
<P>
-So if you specify as the ACTION URL the file which contains the form
-itself, the form will be redisplayed with same values as entered the first
-time. (See eg/x/neu.htm for an example.)
+NOTE: There are also two modules (<EM>HTML::EmbperlChain</EM> and <EM>Apache::EmbperlFilter</EM>) which provides you with the possibility to chain <EM>Embperl</EM> and other modules together.
-<DT><STRONG><A NAME="item_TEXTAREA">TEXTAREA, /TEXTAREA</A></STRONG><DD>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_MAILHOST">EMBPERL_MAILHOST</A></H2>
<P>
-The <A href="Embperl.pod.3.html#item_TEXTAREA">TEXTAREA</A> tag is treated exactly like other input fields.
+Specifies which host the <A href="Embperl.pod.9.html#MailFormTo_MailTo_Subject_R">MailFormTo</A> function uses as SMTP server. Default is <STRONG>localhost</STRONG>.
-<DT><STRONG><A NAME="item_META">META HTTP-EQUIV=</A></STRONG><DD>
<P>
-<meta http-equiv= ... > will over-ride the corresponding http header.
-This keeps Netscape from asking the user to reload the document when the
-content-type differs between the http header and the meta http-equiv.
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_MAILFROM">EMBPERL_MAILFROM</A></H2>
+<P>
+(only 1.2.1 or above) Specifies which the email address that is used as
+sender by <A href="Embperl.pod.9.html#MailFormTo_MailTo_Subject_R">MailFormTo</A>. Default is <STRONG>www-server@server_name</STRONG>.
<P>
-This can also be used to set http headers. When running under mod_perl
-http-headers can also be set by the function <STRONG>header_out</STRONG>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_MAILDEBUG">EMBPERL_MAILDEBUG</A></H2>
+<P>
+(only 1.2.1 or above) Debugsetting for Net::SMTP. Default is 0.
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_MAIL_ERRORS_TO">EMBPERL_MAIL_ERRORS_TO</A></H2>
+<P>
+If set all errors will be send to the email adress given.
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COOKIE_NAME">EMBPERL_COOKIE_NAME</A></H2>
+<P>
+(only 1.2b4 or above) Set the name that Embperl uses when it sends the
+cookie with the session id. Default is EMBPERL_UID.
<P>
-<PRE> Example of how to set a http header:
-</PRE>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COOKIE_DOMAIN">EMBPERL_COOKIE_DOMAIN</A></H2>
<P>
-<PRE> <META HTTP-EQUIV="Language" CONTENT="DE">
-</PRE>
+(only 1.2b4 or above) Set the domain that Embperl uses for the cookie with
+the session id. Default is none.
+
<P>
-<PRE> This is the same as using the Apache function
-</PRE>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COOKIE_PATH">EMBPERL_COOKIE_PATH</A></H2>
<P>
-<PRE> [- $req_rec ->� header_out("Language" => "DE"); -]
-</PRE>
-<DT><STRONG><A NAME="item_A">A, EMBED, IMG, IFRAME, FRAME, LAYER</A></STRONG><DD>
+(only 1.2b4 or above) Set the path that Embperl uses for the cookie with
+the session id. Default is none.
+
<P>
-The output of perl blocks inside the <CODE>HREF</CODE> attribute of the <A href="Embperl.pod.3.html#item_A">A</A> Tags and the
-<CODE>SRC</CODE> attribute of the other Tags are URL escaped instead of HTML escaped. (see
-also <EM>$escmode</EM>). Also when inside such a URL, <EM>Embperl</EM> expands array refernces to URL paramter syntax. Example:
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_COOKIE_EXPIRES">EMBPERL_COOKIE_EXPIRES</A></H2>
+<P>
+(only 1.2b4 or above) Set the expiration date that Embperl uses for the
+cookie with the session id. Default is none.
<P>
-<PRE> [-
- %A = (A => 1, B => 2) ;
- @A = (X, 9, Y, 8, Z, 7)
- -]
-</PRE>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_SESSION_CLASSES">EMBPERL_SESSION_CLASSES</A></H2>
<P>
-<PRE> <A HREF="<A HREF="http://localhost/tests">http://localhost/tests</A>?[+ [ %A ] +]">
- <A HREF="<A HREF="http://localhost/tests">http://localhost/tests</A>?[+ \@A +]">
-</PRE>
+Space separted list of object store and lock manager for Apache::Session
+(see <A href="Embperl.pod.7.html#Session_handling">Session handling</A>)
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="EMBPERL_SESSION_ARGS">EMBPERL_SESSION_ARGS</A></H2>
<P>
-is expanded by <EM>Embperl</EM> to
+List of arguments for Apache::Session classes (see <A href="Embperl.pod.7.html#Session_handling">Session handling</A>) Example:
<P>
-<PRE> <A HREF="<A HREF="http://localhost/tests?A=1&">http://localhost/tests?A=1&</A>;B=2">
- <A HREF="<A HREF="http://localhost/tests?X=9&">http://localhost/tests?X=9&</A>;Y=8&Z=7">
+<PRE> PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=www Password=secret"
</PRE>
-</DL>
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.2.html">PREV (Runtime configuration)</a>] [<a href="Embperl.pod.4.html">NEXT (Variable scope and cleanup)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.2.html">PREV (Operating-Modes)</a>] [<a href="Embperl.pod.4.html">NEXT (SYNTAX)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.8 +548 -33 modperl-site/embperl/Embperl.pod.4.html
Index: Embperl.pod.4.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.4.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- Embperl.pod.4.html 1999/08/19 05:01:31 1.7
+++ Embperl.pod.4.html 2000/02/20 20:29:32 1.8
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Variable scope and cleanup</TITLE>
+<TITLE>SYNTAX</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Variable_scope_and_cleanup">Variable scope and cleanup</a></strong></h1>
+<A NAME="SYNTAX">SYNTAX</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,59 +16,574 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.3.html">PREV (SYNTAX)</a>] [<a href="Embperl.pod.5.html">NEXT (Predefined variables)</a>] <br><hr>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.3.html">PREV (Runtime configuration)</a>] [<a href="Embperl.pod.5.html">NEXT (Variable scope and cleanup)</a>] <br> <UL>
+
+ <LI><A href="Embperl.pod.4.html#_Perl_code_">[+ Perl code +]</A>
+ <LI><A href="Embperl.pod.4.html#_Perl_code_">[- Perl code -]</A>
+ <LI><A href="Embperl.pod.4.html#_Perl_Code_">[! Perl Code !]</A>
+ <LI><A href="Embperl.pod.4.html#_Perl_code_">[* Perl code *]</A>
+ <LI><A href="Embperl.pod.4.html#_Some_Text_Comments_">[# Some Text #] (Comments)</A>
+ <LI><A href="Embperl.pod.4.html#_Cmd_Arg_Meta_Commands_">[$ Cmd Arg $] (Meta-Commands)</A>
+ <LI><A href="Embperl.pod.4.html#HTML_Tags">HTML Tags</A>
+ </UL>
+<hr>
+<P>
+Embperl understands two categories of commands. The first one are special
+Embperl commands, and the second category consists of some HTML tags which
+can trigger special processing. Embperl commands can span multiple lines
+and need not start or end at a line boundary.
+
+<P>
+Before the special Embperl commands are processed, and for the VALUE
+attribute of the INPUT tag (see below), all HTML tags are removed and
+special HTML characters are translated to their ASCII values (e.g.,
+`&lt;' is translated to `<'). You can avoid this behavior by
+preceding the special character or HTML tag with a backslash. This is done
+in case your favorite (WYSIWYG) HTML editor inserts tags like line breaks
+or formatting into your Embperl commands where you don't want them.
+
+<P>
+<STRONG>VERY IMPORTANT NOTE:</STRONG> If you do use an ASCII editor to write your HTML documents, you should set
+the option <STRONG>optRawInput</STRONG> so that Embperl does not preprocess your source. You can also HTML-escape
+your code (i.e. write `&lt;' instead of `<'), to avoid ambiguity. In
+most cases it will also work without the optRawInput and HTML-escaping, but
+in some cases Embperl will detect an HTML tag were there isn't one.
+
+<P>
+<STRONG>If you have any trouble with your code, especially with HTML tags or filehandles
+in your Perl code, be sure to understand input- and output- escaping and
+unescaping. Read the section
+<A href="Embperl.pod.11.html#Inside_Embperl_How_the_embedde">"Inside Embperl"</A>
+to see what's going on!!</STRONG>
+
+
+
+<P>
+All Embperl commands start with a `[' and end with a `]'. To get a real `['
+you must enter `[['.
+
+<P>
+Embperl does not use SGML comments (i.e., <! ... !> or similar things) because some HTML editors can't create them,
+or it's much more complicated. Since every HTML editor takes (or <STRONG>should</STRONG> take) `[' and `]' as normal text, there should be no problem.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Perl_code_">[+ Perl code +]</A></H2>
+<P>
+Replace the command with the result you get from evaluating the Perl code.
+The Perl code can be anything which can be used as an argument to a Perl
+eval statement. (See <A href="Embperl.pod.8.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> below for restrictions.) Examples:
+
+<P>
+<PRE> [+ $a +] Replaces the [+ $a +] with the content of
+ the variable $a
+</PRE>
+<P>
+<PRE> [+ $a+1 +] (Any expression can be used)
+</PRE>
+<P>
+<PRE> [+ $x[$i] +] (Arrays, hashes, and more complex
+ expressions work)
+</PRE>
+<P>
+<CODE>NOTE:</CODE> Whitespace is ignored. The output will be automatically HTML-escaped (e.g.,
+`<' is translated to `&lt;') depending on the value of the variables <A href="Embperl.pod.6.html#item__escmode">$escmode</A>. You do not have to worry about it.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Perl_code_">[- Perl code -]</A></H2>
+<P>
+Executes the Perl code, but deletes the whole command from the HTML output.
+
+<P>
+Examples:
+
+<P>
+<PRE> [- $a=1 -] Set the variable $a to one.
+ No output will be generated.
+</PRE>
+<P>
+<PRE> [- use SomeModule ; -] You can use other modules. NOTE the semikolon!
+</PRE>
+<P>
+<PRE> [- $i=0; while ($i<5) {$i++} -] Even more complex
+ statements or multiple
+ statements are possible.
+</PRE>
+<P>
+<CODE>NOTE:</CODE> Statements like if, while, for, etc., must be contained in a single Embperl
+command. You cannot have the if in one command block and the terminating
+`}' or else in another.
+
+<P>
+<CODE>NOTE:</CODE> To define subroutines, use <A href="Embperl.pod.4.html#_Perl_Code_">[! Perl Code !]</A> (see below) instead of [- ... -] to avoid recompilation of the subroutine
+on every request.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Perl_Code_">[! Perl Code !]</A></H2>
+<P>
+Same as [- Perl Code -] with the exception that the code is only executed
+at the first request. This could be used to define subroutines, or do
+one-time initialization.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Perl_code_">[* Perl code *]</A></H2>
+<P>
+(only version 1.2b2 or higher) <STRONG>EXPERIMENTAL!</STRONG>
+
+
+
+<P>
+This is similar to [- Perl Code -], the main difference is, while [- Perl
+Code -], has always it's own scope, all [* Perl code *] blocks runs in the
+same scope. This gives you the possibilty to define ``local'' variables
+with a scope of the whole page. Normaly you don't need to use local,
+because Embperl takes care of separate namespaces of different documents
+and cleanup after the request is finished, but in special cases it's
+necessary. For example if you want recursivly call an Embperl document via
+Execute.
+
+<P>
+There is a second reason to use the [* Perl code *] instead of the [- Perl
+Code -]. If you like to use perl's control structures. Perl's if, while,
+for etc. can <STRONG>not</STRONG> span mulitple [- Perl Code -] blocks, but it can span multiple [* Perl Code
+*].
+
<P>
-The scope of a variable declared with <STRONG>my</STRONG> or <STRONG>local</STRONG> ends at the end of the enclosing [+/- ... -/+] block; the [+/- ... -/+]
-blocks act much like Perl's { ... } in that regard.
+<PRE> Example:
+</PRE>
+<P>
+<PRE> [* foreach $i (1..10) { *]
+
+ [- $a = $i + 5 -]
+ loop count + 5 = [+ $a +] <br>
+</PRE>
+<P>
+<PRE> [* } *]
+</PRE>
+<P>
+<PRE> The following B<won't> work:
+</PRE>
+<P>
+<PRE> [- foreach $i (1..10) { -]
+ some text here <br>
+ [- } -]
+</PRE>
+<P>
+The same can be done with Embperl <A href="Embperl.pod.4.html#_Cmd_Arg_Meta_Commands_">meta commands</A> (see below)
+<P>
+<PRE> [$ foreach $i (1..10) $]
+
+ [- $a = $i + 5 -]
+ loop count + 5 = [+ $a +] <br>
+</PRE>
+<P>
+<PRE> [$ endforeach $]
+</PRE>
<P>
-Global variables (everything not declared with <STRONG>my</STRONG> or <STRONG>local</STRONG>) will be undef'ed at the end of each request, so you don't need to worry
-about any old variables laying around and causing suspicious results. This
-is only done for variables in the package the code is eval'ed in -- every
-variable that does not have an explicit package name. All variables with an
-explicit package name (i.e., in modules you use) will stay valid until the
-httpd child process dies. Embperl will change the current package to a
-unique name for every document, so the influence between different
-documents is kept to a minimum. You can set the name of the package with <STRONG>EMBPERL_PACKAGE</STRONG>. (See also
-<A href="Embperl.pod.7.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A>.)
+<STRONG>NOTE 1:</STRONG> [* ... *] blocks _must_ always end with a <STRONG>;</STRONG>,<STRONG>{</STRONG> or <STRONG>}</STRONG>
+
+
<P>
-Since a CGI script is always a process of its own, you don't need to worry
-about that when you use Embperl as a CGI script.
+<STRONG>NOTE 2:</STRONG> [* ... *] cannot apear inside a html tag that is interpreted by Embperl
+(unless you disable the interpretation of such tags like table, input etc.)
<P>
-If you need to declare variables which need to live longer than just one
-HTTP request (for example, a database handle), you must either put it's
-name in the hash <CODE>%CLEANUP</CODE> or declare them in another package (i.e., $Persistent::handle instead of
-$handle).
+<STRONG>NOTE 3:</STRONG> Since the execution of [- ... -] and metacommands is controlled by Embperl,
+there is a much better debugging output in the logfile for this two ones.
+Also no restriction where they can be used apply to meta-commands. You can
+use them anywhere even inside of html tags that are interpreted by Embperl.
<P>
-If you want to use the strict pragma, you can do this by using the <STRONG>var</STRONG> metacommand to declare your variables.
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Some_Text_Comments_">[# Some Text #] (Comments)</A></H2>
+<P>
+(only version 1.2b2 or higher)
<P>
-<CODE>NOTE:</CODE> Bacause Apache::DBI has its own namespace, this module will work together
-with Embperl to maintain your persistent database connection.
+This is a comment block. Everything between the [# and the #] will be
+removed from the output.
<P>
-You can disable the automatic cleanup of global variables with
-<STRONG>EMBPERL_OPTIONS</STRONG> or the <STRONG>cleanup</STRONG> parameter of the <STRONG>Execute</STRONG>
-function.
+<STRONG>NOTE 1:</STRONG> The [* ... *] blocks are interpreted before the comment block, so they are
+executed also inside a comment.
<P>
-You can define expections to the cleanup rule with the hash <STRONG>%CLEANUP</STRONG>.
+<STRONG>NOTE 2:</STRONG> Everything (except [* ... *]) is really removed from the source, so you can
+also use the [# ... #] block to take a part out of your document.
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_Cmd_Arg_Meta_Commands_">[$ Cmd Arg $] (Meta-Commands)</A></H2>
<P>
-If you like to do your own cleanup you can define a subroutine <STRONG>CLEANUP</STRONG>
-in your document. This will be called right before the variables are
-cleaned up, but after the connection to the client is closed.
+Execute an Embperl metacommand. <STRONG>Cmd</STRONG> can be one of the following. (<STRONG>Arg</STRONG> varies depending on <Cmd>).
+<DL>
+<DT><STRONG><A NAME="item_if">if, elsif, else, endif</A></STRONG><DD>
<P>
-<PRE> EXAMPLE:
+Everything following the <STRONG>if</STRONG> metacommand until the <STRONG>else</STRONG>,
+<STRONG>elsif</STRONG>, or <STRONG>endif</STRONG> is only output if the Perl expression given in
+<STRONG>Arg</STRONG> is true. <STRONG>else</STRONG> and <STRONG>elsif</STRONG> work similarly.
+
+<P>
+Example:
+
+<P>
+<PRE> [$ if $ENV{REQUEST_METHOD} eq 'GET' $]
+ Method was GET<BR>
+ [$ else $]
+ Method other than GET used<BR>
+ [$ endif $]
</PRE>
+<P>
+This will send one of the two sentences to the client, depending on the
+request method used to retrieve the document.
+
+<DT><STRONG><A NAME="item_while">while, endwhile</A></STRONG><DD>
+<P>
+Executes a loop until the <STRONG>Arg</STRONG> given to <STRONG>while</STRONG> is false.
+
+<P>
+Example: (see eg/x/loop.htm)
+
+<P>
+<PRE> [- $i = 0; @k = keys %ENV -]
+ [$ while ($i &lt; $#k) $]
+ [+ $k[$i] +] = [+ $ENV{$k[$i]} +]<BR>
+ [- $i++ -]
+ [$ endwhile $]
+</PRE>
+<P>
+This will send a list of all environment variables to the client.
+
+<P>
+NOTE: The `&lt;' is translated to `<' before calling Perl eval,
+unless optRawInput is set.
+
+<DT><STRONG><A NAME="item_do">do, until</A></STRONG><DD>
+<P>
+Executes a loop until the <STRONG>Arg</STRONG> given to <STRONG>until</STRONG> is true.
+
+<P>
+<PRE> Example:
+</PRE>
+<P>
+<PRE> [- $i = 0 -]
+ [$ do $]
+ [+ $i++ +] <BR>
+ [$ until $i > 10 $]
+</PRE>
+<DT><STRONG><A NAME="item_foreach">foreach, endforeach</A></STRONG><DD>
+<P>
+Executes a loop for each element of the second <STRONG>Arg</STRONG>, setting the first <STRONG>Arg</STRONG> accordingly.
+
+<P>
+<PRE> Example:
+</PRE>
+<P>
+<PRE> [- @arr = (1, 3, 5) -]
+ [$ foreach $v @arr $]
+ [+ $v +] <BR>
+ [$ endforeach $]
+</PRE>
+<DT><STRONG><A NAME="item_hidden">hidden</A></STRONG><DD>
+<P>
+<STRONG>Arg</STRONG> consists of zero, one or two names of hashes (with or without the leading
+%) and an optional array as third parameter. The
+<STRONG>hidden</STRONG> metacommand will generate hidden fields for all data contained in the first
+hash but not in the second hash. The default used for the first hash is <CODE>%fdat</CODE>, <CODE>%idat</CODE> is used for the second.
+
+<P>
+If the third parameter is specified, the fields are written in the order
+they appear in this array. That is, all keys of the first hash must be
+properly sorted in this array. This is intended for situations where you
+want to pass data from one form to the next, for example, two forms which
+should be filled in one after the other. (Examples might be an input form
+and a second form to review and accept the input, or a Windows-style
+``wizard''). Here you can pass along data from previous forms in hidden
+fields. (See eg/x/neu.htm for an example.) If you use just the 'hidden'
+command without parameters, it simply generates hidden fields for all form
+fields submitted to this document which aren't already contained in another
+input field.
+
+<P>
+Example:
+
+<P>
+<PRE> <FORM ACTION="inhalt.htm" METHOD="GET">
+ <INPUT TYPE="TEXT" NAME="field1">
+ [$ hidden $]
+ </FORM>
+</PRE>
+<P>
+If you request this with <A
+HREF="http://host/doc.htm?field1=A&field2=B&field3=C">http://host/doc.htm?field1=A&field2=B&field3=C</A>
+
+
+<P>
+the output will be
+
+<P>
+<PRE> <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>
+</PRE>
+<P>
+<CODE>NOTE:</CODE> This should only be used for a small amount of data, since the hidden
+fields are sent to the browser, which sends it back with the next request.
+If you have a large amount of data, store it in a file with a unique name
+and send only the filename in a hidden field. Be aware of the fact that the
+data can be change by the browser if the user doesn't behave exactly as you
+expect. Users have a nasty habit of doing this all of the time. Your
+program should be able to handle such situations properly.
+
+<DT><STRONG><A NAME="item_var">var</A></STRONG><DD>
+<P>
+The var command declares one or more variables for use within this Embperl
+document and sets the <STRONG>strict</STRONG> pragma. The variable names must be supplied as space-separated list.
+
+<P>
+Example: [$var <CODE>$a</CODE> <CODE>%b</CODE> <CODE>@c</CODE> $]
+
+<P>
+This is the same as writing the following in normal Perl code:
+
+<P>
+<PRE> use strict ;
+ use vars qw($a %b @c) ;
+</PRE>
+<P>
+NOTE 1: `use strict' within an Embperl document will only apply to the
+block in which it occurs.
+
+<DT><STRONG><A NAME="item_sub">sub</A></STRONG><DD>
+<P>
+(Only Embperl 1.2b5 and above)
+
+<P>
+Defines a Embperl subroutine. Example:
+
+<P>
+<PRE> [$ sub foo $]
+ <p> Here we do something </p>
+ [$ endsub $]
+</PRE>
+<P>
+You can call this subroutine either as a normal Perl subroutine
+
+<P>
+<PRE> [- foo -]
+</PRE>
+<P>
+or via the HTML::Embperl::Execute function.
+
+<P>
+<PRE> [- Execute ('#foo') # short form -]
+ [- Execute ({ sub => 'foo'}) # long form -]
+</PRE>
+<P>
+The difference is that the Execute function will reset the internal states
+of Embperl like they were before the subrountine call, when the subroutine
+returns. Also Execute could handle recursive call, which currently not work
+when calling it as a Perl subroutine.
+
+<P>
+You may also pass Parameters to the subroutine:
+
+<P>
+<PRE> [$ sub foo $]
+ [- $p = shift -]
+ <p> Here we show the first parameter [+ $p +]</p>
+ [$ endsub $]
+</PRE>
+<P>
+<PRE>
+ [- foo ('value') -]
+</PRE>
+<P>
+If you have a couple of commonly used subroutines you can define then in
+one file and import them into the modules where they are neccesary:
+
+<P>
+<PRE> [- Execute ({ inputfile => 'mylib.htm', import => 1 }) -]
+</PRE>
+<P>
+This will import all subroutines from the file <EM>mylib.htm</EM> into the current page where they could call just as a normal Perl
+subroutine.
+
+</DL>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="HTML_Tags">HTML Tags</A></H2>
+<P>
+Embperl recognizes the following HTML tags specially. All others are simply
+passed through, as long as they are not part of a Embperl command.
+
+<DL>
+<DT><STRONG><A NAME="item_TABLE">TABLE, /TABLE, TR, /TR</A></STRONG><DD>
+<P>
+Embperl can generate dynamic tables (one- or two-dimensional). You only
+need to specify one row or column.
+
+<P>
+Embperl generates as many rows or columns as necessary. This is done by
+using the magic variables $row, $col, and $cnt. If you don't use
+$row/$col/$cnt within a table, Embperl does nothing and simply passes the
+table through.
+
+<P>
+Embperl checks if any of $row, $col, or <CODE>$cnt</CODE> is used. Embperl
+repeats all text between <table> and </table>, as long the
+expressions in which <CODE>$row</CODE> or <CODE>$cnt</CODE> occurs is/are
+defined.
+
+<P>
+Embperl repeats all text between <tr> and </tr>, as long the
+expressions in which <CODE>$col</CODE> or <CODE>$cnt</CODE> occurs is/are
+defined.
+
+<P>
+See also <A href="Embperl.pod.6.html#_tabmode">$tabmode</A> (below) for end-of-table criteria.
+
+<P>
+Examples: (see eg/x/table.htm for more examples)
+
+<P>
+<PRE> [- @k = keys %ENV -]
+ <TABLE>
+ <TR>
+ <TD>[+ $i=$row +]</TD>
+ <TD>[+ $k[$row] +]</TD>
+ <TD>[+ $ENV{$k[$i]} +]</TD>
+ </TR>
+ </TABLE>
+</PRE>
+<P>
+This will show all entries in array <CODE>@k</CODE> (which contains the
+keys from %ENV), so the whole environment is displayed (as in the <STRONG>while</STRONG>
+example), with the first column containing the zero-based index, the second
+containing the content of the variable name, and the third the environment
+variable's value.
+
+<P>
+This could be used to display the result of a database query if you have
+the result in an array. You may provide as many columns as you need. It is
+also possible to call a 'fetch' subroutine in each table row.
+
+<DT><STRONG><A NAME="item_TH">TH, /TH</A></STRONG><DD>
+<P>
+The <TH> tag is interpreted as a table heading. If the whole row is
+made up of <TH> </TH> instead of <TD> </TD>, it is
+treated as a column heading. Everything else will be treated as row
+headings in the future, but are not now: everything else is ignored in the
+current version.
+
+<DT><STRONG><A NAME="item_DIR">DIR, MENU, OL, UL, DL, SELECT, /DIR, /MENU,
+/OL, /UL, /DL, /SELECT</A></STRONG><DD>
+<P>
+Lists and dropdowns or list boxes are treated exactly as one- dimensional
+tables. Only <A href=".html#_row">$row</A>, <A href=".html#_maxrow">$maxrow</A>, <A href=".html#_col">$col</A>, <A href=".html#_maxcol">$maxcol</A> and <A href="Embperl.pod.6.html#_tabmode">$tabmode</A>
+are honored. <CODE>$col</CODE> and <CODE>$maxcol</CODE> are ignored. See
+eg/x/lists.htm for an example.
+
+<DT><STRONG><A NAME="item_OPTION">OPTION</A></STRONG><DD>
+<P>
+Embperl checks if there is a value from the form data for a specific option
+in a menu. If so, this option will be pre-selected.
+
+<P>
+Example:
+
+<P>
+<FORM METHOD=``POST''> <P>Select Tag</P>
+
+<P>
+<PRE> If you request this document with list.htm?SEL1=x
+ you can specify that the element which has a value
+ of x is initially selected
+</PRE>
+<P>
+<PRE> <P><SELECT NAME="SEL1">
+ <OPTION VALUE="[+ $v[$row] +]">
+ [+ $k[$row] +]
+ </OPTION>
+ </SELECT></P>
+</FORM>
+</PRE>
+<DT><STRONG><A NAME="item_INPUT">INPUT</A></STRONG><DD>
+<P>
+The INPUT tag interacts with the hashes <CODE>%idat</CODE> und <CODE>%fdat</CODE>. If the input tag has no value, and a key exists with the same text as the
+NAME attribute of the input tag, Embperl will generate a VALUE attribute
+with the corresponding value of the hash key. All values of <INPUT> tags are stored in the hash <CODE>%idat</CODE>, with NAME as the hash key and VALUE as the hash value. Special processing
+is done for TYPE=RADIO and TYPE=CHECKBOX. If the VALUE attribute contains
+the same text as the value of the hash the CHECKED attribute is inserted,
+else it is removed.
+
+<P>
+So if you specify as the ACTION URL the file which contains the form
+itself, the form will be redisplayed with same values as entered the first
+time. (See eg/x/neu.htm for an example.)
+
+<DT><STRONG><A NAME="item_TEXTAREA">TEXTAREA, /TEXTAREA</A></STRONG><DD>
+<P>
+The <A href="Embperl.pod.4.html#item_TEXTAREA">TEXTAREA</A> tag is treated exactly like other input fields.
+
+<DT><STRONG><A NAME="item_META">META HTTP-EQUIV=</A></STRONG><DD>
+<P>
+<meta http-equiv= ... > will over-ride the corresponding http header.
+This keeps Netscape from asking the user to reload the document when the
+content-type differs between the http header and the meta http-equiv.
+
+<P>
+This can also be used to set http headers. When running under mod_perl
+http-headers can also be set by the function <STRONG>header_out</STRONG>
+
+
+
+<P>
+<PRE> Example of how to set a http header:
+</PRE>
+<P>
+<PRE> <META HTTP-EQUIV="Language" CONTENT="DE">
+</PRE>
+<P>
+<PRE> This is the same as using the Apache function
+</PRE>
+<P>
+<PRE> [- $req_rec ->� header_out("Language" => "DE"); -]
+</PRE>
+<DT><STRONG><A NAME="item_A">A, EMBED, IMG, IFRAME, FRAME, LAYER</A></STRONG><DD>
+<P>
+The output of perl blocks inside the <CODE>HREF</CODE> attribute of the <A href="Embperl.pod.4.html#item_A">A</A> Tags and the
+<CODE>SRC</CODE> attribute of the other Tags are URL escaped instead of HTML escaped. (see
+also <EM>$escmode</EM>). Also when inside such a URL, <EM>Embperl</EM> expands array refernces to URL paramter syntax. Example:
+
+<P>
+<PRE> [-
+ %A = (A => 1, B => 2) ;
+ @A = (X, 9, Y, 8, Z, 7)
+ -]
+</PRE>
+<P>
+<PRE> <A HREF="<A HREF="http://localhost/tests">http://localhost/tests</A>?[+ [ %A ] +]">
+ <A HREF="<A HREF="http://localhost/tests">http://localhost/tests</A>?[+ \@A +]">
+</PRE>
+<P>
+is expanded by <EM>Embperl</EM> to
+
<P>
-<PRE> [! sub CLEANUP { close FH ; } !]
+<PRE> <A HREF="<A HREF="http://localhost/tests?A=1&">http://localhost/tests?A=1&</A>;B=2">
+ <A HREF="<A HREF="http://localhost/tests?X=9&">http://localhost/tests?X=9&</A>;Y=8&Z=7">
</PRE>
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.3.html">PREV (SYNTAX)</a>] [<a href="Embperl.pod.5.html">NEXT (Predefined variables)</a>] <br>
+</DL>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.3.html">PREV (Runtime configuration)</a>] [<a href="Embperl.pod.5.html">NEXT (Variable scope and cleanup)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.16 +33 -324 modperl-site/embperl/Embperl.pod.5.html
Index: Embperl.pod.5.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.5.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- Embperl.pod.5.html 2000/01/06 08:33:30 1.15
+++ Embperl.pod.5.html 2000/02/20 20:29:32 1.16
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Predefined variables</TITLE>
+<TITLE>Variable scope and cleanup</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Predefined_variables">Predefined variables</a></strong></h1>
+<A NAME="Variable_scope_and_cleanup">Variable scope and cleanup</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,350 +16,59 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.4.html">PREV (Variable scope and cleanup)</a>] [<a href="Embperl.pod.6.html">NEXT (Session handling)</a>] <br> <UL>
-
- <LI><A href="Embperl.pod.5.html#_ENV">%ENV</A>
- <LI><A href="Embperl.pod.5.html#_fdat">%fdat</A>
- <LI><A href="Embperl.pod.5.html#_ffld">@ffld</A>
- <LI><A href="Embperl.pod.5.html#_idat">%idat</A>
- <LI><A href="Embperl.pod.5.html#_udat_only_1_2b1_or_higher_">%udat (only 1.2b1 or higher)</A>
- <LI><A href="Embperl.pod.5.html#_mdat_only_1_2b2_or_higher_">%mdat (only 1.2b2 or higher)</A>
- <LI><A href="Embperl.pod.5.html#_row_col">$row, $col</A>
- <LI><A href="Embperl.pod.5.html#_maxrow_maxcol">$maxrow, $maxcol</A>
- <LI><A href="Embperl.pod.5.html#_cnt">$cnt</A>
- <LI><A href="Embperl.pod.5.html#_tabmode">$tabmode</A>
- <LI><A href="Embperl.pod.5.html#_escmode">$escmode</A>
- <LI><A href="Embperl.pod.5.html#_req_rec">$req_rec</A>
- <LI><A href="Embperl.pod.5.html#LOG">LOG</A>
- <LI><A href="Embperl.pod.5.html#OUT">OUT</A>
- <LI><A href="Embperl.pod.5.html#_param">@param</A>
- <LI><A href="Embperl.pod.5.html#_http_headers_out_only_1_2b10_a">%http_headers_out (only 1.2b10 and above)</A>
- <LI><A href="Embperl.pod.5.html#_optXXX_dbgXXX">$optXXX $dbgXXX</A>
- <LI><A href="Embperl.pod.5.html#_CLEANUP">%CLEANUP</A>
- </UL>
-<hr>
-<P>
-Embperl has some special variables which have a predefined meaning.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_ENV">%ENV</A></H2>
-<P>
-Contains the environment as seen from a CGI script.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_fdat">%fdat</A></H2>
-<P>
-Contains all the form data sent to the script by the calling form. The NAME
-attribute builds the key and the VALUE attribute is used as the hash value.
-Embperl doesn't care if it is called with the GET or POST method, but there
-may be restrictions on the length of parameters using GET -- not from
-Embperl, but perhaps from the web server, especially if you're using
-Embperl's CGI mode -- it is safer to use POST.
-
-<P>
-If multiple fields with the same name send to a Embperl page they will put
-in the same hash element and separated be tabs. You can split it up in an
-array, by writting:
-
-<P>
-<PRE> @array = split (/\t/, $fdat{'fieldname'}) ;
-</PRE>
-<P>
-Embperl also supports ENCTYPE multipart/form-data, which is used for file
-uploads. The entry in <CODE>%fdat</CODE> corresponding to the file field
-will be a filehandle, as with CGI.pm. (Embperl uses CGI.pm internally to
-process forms encoded with multipart/form-data.)
-
-<P>
-File upload example:
-
-<P>
-<PRE> HTML page:
-</PRE>
-<P>
-<PRE> <FORM METHOD="POST" ENCTYPE="multipart/form-data">
- <INPUT TYPE="FILE" NAME="ImageName">
- </FORM>
-</PRE>
-<P>
-<PRE> Embperl ACTION:
-</PRE>
-<P>
-<PRE> [- if (defined $fdat{ImageName}) {
- open FILE, "> /tmp/file.$$";
- print FILE $buffer
- while read($fdat{ImageName}, $buffer, 32768);
- close FILE;
- }
- -]
-
-</PRE>
-<P>
-When you have installed CGI.pm 2.46 or above you may also retrieve the
-filename (local filename, as it was on the browser side) and the
-informations provied by the CGI.pm uploadInfo function. To get the filename
-just print out the value of the correspondig <CODE>%fdat</CODE> entry,
-instead of using it as a filehandle. To get the <STRONG>uploadInfo</STRONG> use the fieldname with a dash in front of it:
-
-<P>
-<PRE> Example:
-</PRE>
-<P>
-<PRE> # ImageName is the NAME of the field, you must replace it with whatever
- # name is given in your HTML code
- Filename: [+ $fdat{ImageName} +] <br>
- Content-Type: [+ $fdat{-ImageName} -> {'Content-Type'} +] <br>
-</PRE>
-<P>
-<STRONG>NOTE:</STRONG> The way <STRONG>uploadInfos</STRONG> are accessed before 1.2b11 are not supported anymore.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_ffld">@ffld</A></H2>
-<P>
-Contains all the field names in the order in which they were sent by the
-browser. This is normally -- but not necessarily -- the order in which they
-appear in your form.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_idat">%idat</A></H2>
-<P>
-Contains all the values from all input tags processed so far.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_udat_only_1_2b1_or_higher_">%udat (only 1.2b1 or higher)</A></H2>
-<P>
-You can use <STRONG>%udat</STRONG> to store per user data. As long as you don't use %udat, nothing happens,
-but as soon as you write anything to %udat, Embperl creates a session id
-and sends it via a cookie to the browser. The data you have written to
-<CODE>%udat</CODE> is stored by Apache::Session. The next time the same
-user request an Embperl page, the browser sends the cookie with the session
-id back and Embperl fill the <CODE>%udat</CODE> hash from Apache::Session
-with just the same values as you have stored for that user. (See also <A href="Embperl.pod.6.html#Session_handling">Session handling</A>)
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_mdat_only_1_2b2_or_higher_">%mdat (only 1.2b2 or higher)</A></H2>
-<P>
-You can use <STRONG>%mdat</STRONG> to store per module/page data. As long as you don't use %mdat, nothing
-happens, but as soon as you write anything to %mdat, Embperl creates a
-session id and stores the data via Apache::Session. The next time any user
-hits the same Embperl page, Embperl fill the <CODE>%mdat</CODE> hash from
-Apache::Session with just the same values as you have stored within the
-last request to that page. (See also <A href="Embperl.pod.6.html#Session_handling">Session handling</A>)
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_row_col">$row, $col</A></H2>
-<P>
-Row and column counts for use in dynamic tables. (See <A href="Embperl.pod.3.html#HTML_Tags">"HTML tag table"</A>.)
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_maxrow_maxcol">$maxrow, $maxcol</A></H2>
-<P>
-Maxium number of rows or columns to display in a table. To prevent endless
-loops, <CODE>$maxrow</CODE> defaults to 100 and <CODE>$maxcol</CODE> to 10.
-(See <A href="Embperl.pod.3.html#HTML_Tags">"HTML tag table"</A>.)
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_cnt">$cnt</A></H2>
-<P>
-Contains the number of table cells displayed so far. (See <A href="Embperl.pod.3.html#HTML_Tags">"HTML tag table"</A>.)
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_tabmode">$tabmode</A></H2>
-<P>
-Determines how the end of a dynamic table is detected. Tables are always
-limited to the size specified in <CODE>$maxrow</CODE> and $maxcol, but can
-be ended early when the row ($row) and column ($col) variables become
-undefined. <CODE>$tabmode</CODE> operates as follows:
-
-<DL>
-<DT><STRONG><A NAME="item__tabmode">$tabmode = 1</A></STRONG><DD>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.4.html">PREV (SYNTAX)</a>] [<a href="Embperl.pod.6.html">NEXT (Predefined variables)</a>] <br><hr>
<P>
-End table looping when any one of the expressions in the table row using
-<CODE>$row</CODE> returns undefined. The row containing the undefined
-expression is <STRONG>not</STRONG> displayed. Only those expression are observed which contains an access to
-the varibale $row.
+The scope of a variable declared with <STRONG>my</STRONG> or <STRONG>local</STRONG> ends at the end of the enclosing [+/- ... -/+] block; the [+/- ... -/+]
+blocks act much like Perl's { ... } in that regard.
-<DT><STRONG>$tabmode = 2</STRONG><DD>
<P>
-End when an expression with <CODE>$row</CODE> becomes undefined. The row
-containing the undefined expression <STRONG>is</STRONG> displayed.
+Global variables (everything not declared with <STRONG>my</STRONG> or <STRONG>local</STRONG>) will be undef'ed at the end of each request, so you don't need to worry
+about any old variables laying around and causing suspicious results. This
+is only done for variables in the package the code is eval'ed in -- every
+variable that does not have an explicit package name. All variables with an
+explicit package name (i.e., in modules you use) will stay valid until the
+httpd child process dies. Embperl will change the current package to a
+unique name for every document, so the influence between different
+documents is kept to a minimum. You can set the name of the package with <STRONG>EMBPERL_PACKAGE</STRONG>. (See also
+<A href="Embperl.pod.8.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A>.)
-<DT><STRONG>$tabmode = 4</STRONG><DD>
<P>
-End when <CODE>$maxrow</CODE> rows have been displayed.
+Since a CGI script is always a process of its own, you don't need to worry
+about that when you use Embperl as a CGI script.
-</DL>
<P>
-<STRONG>end of row</STRONG>
+If you need to declare variables which need to live longer than just one
+HTTP request (for example, a database handle), you must either put it's
+name in the hash <CODE>%CLEANUP</CODE> or declare them in another package (i.e., $Persistent::handle instead of
+$handle).
-
-
-<DL>
-<DT><STRONG>$tabmode = 16</STRONG><DD>
-<P>
-End table column looping when any one of the expressions in the table
-column using <CODE>$col</CODE> returns undefined. The column containing the
-undefined expression is <STRONG>not</STRONG> displayed. Only those expression are observed which contains an access to
-the varibale $col.
-
-<DT><STRONG>$tabmode = 32</STRONG><DD>
-<P>
-End when an expression with <CODE>$col</CODE> becomes undefined. The column
-containing the undefined expression <STRONG>is</STRONG> displayed.
-
-<DT><STRONG>$tabmode = 64</STRONG><DD>
-<P>
-End when <CODE>$maxcol</CODE> columns have been displayed.
-
-</DL>
-<P>
-The default is <STRONG>17</STRONG>, which is correct for all sort of arrays. You should rarely need to change
-it. The two values can be added together.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_escmode">$escmode</A></H2>
-<P>
-Turn HTML and URL escaping on and off. The default is on ($escmode = 3).
-
-<DL>
-<DT><STRONG><A NAME="item__escmode">$escmode = 3</A></STRONG><DD>
-<P>
-The result of a Perl expression is HTML-escaped (e.g., `>' becomes
-`&gt;') in normal text and URL-escaped (e.g., `&' becomes `%26')
-within of <A href="Embperl.pod.3.html#item_A">A</A>, <CODE>EMBED</CODE>, <CODE>IMG</CODE>, <CODE>IFRAME</CODE>, <CODE>FRAME</CODE> and <CODE>LAYER</CODE> tags.
-
-<DT><STRONG>$escmode = 2</STRONG><DD>
-<P>
-The result of a Perl expression is always URL-escaped (e.g., `&'
-becomes `%26').
-
-<DT><STRONG>$escmode = 1</STRONG><DD>
-<P>
-The result of a Perl expression is always HTML-escaped (e.g., `>'
-becomes `&gt;').
-
-<DT><STRONG>$escmode = 0</STRONG><DD>
-<P>
-No escaping takes place.
-
-</DL>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_req_rec">$req_rec</A></H2>
-<P>
-This variable is only available when running under control of mod_perl. It
-contains the request record needed to access the Apache server API. See <STRONG>perldoc Apache</STRONG> for more information.
-
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="LOG">LOG</A></H2>
-<P>
-This is the filehandle of the Embperl logfile. By writing `print LOG
-``something''' you can add lines to the logfile. NOTE: The logfile line
-should always start with the pid of the current process and continue with a
-four-character signature delimited by a ':', which specifies the log
-reason.
-
-<P>
-Example: print LOG ``[$$]ABCD: your text\n'' ;
-
-<P>
-If you are writing a module for use under Embperl you can say
-
-<P>
-<PRE> tie *LOG, 'HTML::Embperl::Log';
-</PRE>
-<P>
-to get a handle by which you can write to the Embperl logfile.
-
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="OUT">OUT</A></H2>
-<P>
-This filehandle is tied to Embperl's output stream. Printing to it has the
-same effect as using the [+ ... +] block. (See also <A href="Embperl.pod.2.html#EMBPERL_OPTIONS">optRedirectStdout</A>)
+If you want to use the strict pragma, you can do this by using the <STRONG>var</STRONG> metacommand to declare your variables.
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_param">@param</A></H2>
-<P>
-Will be setup by the <STRONG>'param'</STRONG> parameter of the <STRONG>Execute</STRONG> function. Could be used to pass parameters to an Embperl document and back.
-(see
-<A href="Embperl.pod.1.html#By_calling_HTML_Embperl_Execut">Execute</A>
-for further docs)
+<CODE>NOTE:</CODE> Bacause Apache::DBI has its own namespace, this module will work together
+with Embperl to maintain your persistent database connection.
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_http_headers_out_only_1_2b10_a">%http_headers_out (only 1.2b10 and above)</A></H2>
<P>
-You can put any http headers you want to send into this hash. If you set an
-location header Embperl will automaticly set the status to 301 (Redirect).
-Example:
+You can disable the automatic cleanup of global variables with
+<STRONG>EMBPERL_OPTIONS</STRONG> or the <STRONG>cleanup</STRONG> parameter of the <STRONG>Execute</STRONG>
+function.
-<P>
-<PRE> [- $http_headers_out{'Location'} = "<A HREF="http://www.ecos.de/embperl/"">http://www.ecos.de/embperl/"</A>; -]
-</PRE>
<P>
-see also META HTTP-EQUIV=
+You can define expections to the cleanup rule with the hash <STRONG>%CLEANUP</STRONG>.
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_optXXX_dbgXXX">$optXXX $dbgXXX</A></H2>
<P>
-All options (see <A href="Embperl.pod.2.html#EMBPERL_OPTIONS">EMBPERL_OPTIONS</A>) and all debugging flags (see <A href="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A>) can be read and set by the corresponding variables.
+If you like to do your own cleanup you can define a subroutine <STRONG>CLEANUP</STRONG>
+in your document. This will be called right before the variables are
+cleaned up, but after the connection to the client is closed.
-<P>
-<PRE> Example:
-</PRE>
-<P>
-<PRE> [- $optRawInput = 1 -] # Turn the RawInput option on
-
- Now write something here
-</PRE>
<P>
-<PRE> [- $optRawInput = 0 -] # Turn the RawInput option off again
+<PRE> EXAMPLE:
</PRE>
<P>
-<PRE> [+ $dbgCmd +] # Output the state of the dbgCmd flag
+<PRE> [! sub CLEANUP { close FH ; } !]
</PRE>
-<P>
-There are a few exceptions, where the variables can only be read. Setting
-of such options must be done via the config-files. Read-only variables are:
-
-<DL>
-<DT><STRONG><A NAME="item__optDisableVarCleanup">$optDisableVarCleanup</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optSafeNamespace">$optSafeNamespace</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optOpcodeMask">$optOpcodeMask</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optDisableChdir">$optDisableChdir</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optEarlyHttpHeader">$optEarlyHttpHeader</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optDisableFormData">$optDisableFormData</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optAllFormData">$optAllFormData</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optRedirectStdout">$optRedirectStdout</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optAllowZeroFilesize">$optAllowZeroFilesize</A></STRONG><DD>
-<DT><STRONG><A NAME="item__optKeepSrcInMemory">$optKeepSrcInMemory</A></STRONG><DD>
-</DL>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_CLEANUP">%CLEANUP</A></H2>
-<P>
-Embperl cleanups up only variables with are defined within the Embperl
-page. If you want Embperl to cleanup addtional variables you can add them
-to the hash %CLEANUP, with the key set to the variable name and the value
-set to one. The other way round you could prevent Embperl from cleaning up
-some variables, by adding them to this hash, with a values of zero.
-
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.4.html">PREV (Variable scope and cleanup)</a>] [<a href="Embperl.pod.6.html">NEXT (Session handling)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.4.html">PREV (SYNTAX)</a>] [<a href="Embperl.pod.6.html">NEXT (Predefined variables)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.13 +322 -42 modperl-site/embperl/Embperl.pod.6.html
Index: Embperl.pod.6.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.6.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- Embperl.pod.6.html 1999/11/04 06:49:30 1.12
+++ Embperl.pod.6.html 2000/02/20 20:29:32 1.13
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Session handling</TITLE>
+<TITLE>Predefined variables</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Session_handling">Session handling</a></strong></h1>
+<A NAME="Predefined_variables">Predefined variables</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,70 +16,350 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.5.html">PREV (Predefined variables)</a>] [<a href="Embperl.pod.7.html">NEXT ((Safe-)Namespaces and opcode restrictions)</a>] <br><hr>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.5.html">PREV (Variable scope and cleanup)</a>] [<a href="Embperl.pod.7.html">NEXT (Session handling)</a>] <br> <UL>
+
+ <LI><A href="Embperl.pod.6.html#_ENV">%ENV</A>
+ <LI><A href="Embperl.pod.6.html#_fdat">%fdat</A>
+ <LI><A href="Embperl.pod.6.html#_ffld">@ffld</A>
+ <LI><A href="Embperl.pod.6.html#_idat">%idat</A>
+ <LI><A href="Embperl.pod.6.html#_udat_only_1_2b1_or_higher_">%udat (only 1.2b1 or higher)</A>
+ <LI><A href="Embperl.pod.6.html#_mdat_only_1_2b2_or_higher_">%mdat (only 1.2b2 or higher)</A>
+ <LI><A href="Embperl.pod.6.html#_row_col">$row, $col</A>
+ <LI><A href="Embperl.pod.6.html#_maxrow_maxcol">$maxrow, $maxcol</A>
+ <LI><A href="Embperl.pod.6.html#_cnt">$cnt</A>
+ <LI><A href="Embperl.pod.6.html#_tabmode">$tabmode</A>
+ <LI><A href="Embperl.pod.6.html#_escmode">$escmode</A>
+ <LI><A href="Embperl.pod.6.html#_req_rec">$req_rec</A>
+ <LI><A href="Embperl.pod.6.html#LOG">LOG</A>
+ <LI><A href="Embperl.pod.6.html#OUT">OUT</A>
+ <LI><A href="Embperl.pod.6.html#_param">@param</A>
+ <LI><A href="Embperl.pod.6.html#_http_headers_out_only_1_2b10_a">%http_headers_out (only 1.2b10 and above)</A>
+ <LI><A href="Embperl.pod.6.html#_optXXX_dbgXXX">$optXXX $dbgXXX</A>
+ <LI><A href="Embperl.pod.6.html#_CLEANUP">%CLEANUP</A>
+ </UL>
+<hr>
<P>
-From 1.2b1 and higher Embperl is able to handle per user sessions for you.
-You can store any data in the <EM>%udat</EM> hash and if the same user request again an Embperl document, you will see
-the same values in that hash again.
+Embperl has some special variables which have a predefined meaning.
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_ENV">%ENV</A></H2>
<P>
-From 1.2b2 and higher Embperl is able to handle per module/page persitent
-data for you. You can store any data in the <EM>%mdat</EM> hash and if any request comes to the same Embperl document, you will see
-the same values in that hash again.
+Contains the environment as seen from a CGI script.
<P>
-To configure <EM>Embperl</EM> to do session management for you, you must have installed <EM>Apache::Session</EM> (<STRONG>1.00 or higher</STRONG>) and tell Embperl which storage and locker classes you would like to use
-for
-<EM>Apache::Session</EM>. This is done by setting the environement variable
-<CODE>EMBPERL_SESSION_CLASSES</CODE>. You may have a <STRONG>startup.pl</STRONG> for your httpd which looks like this:
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_fdat">%fdat</A></H2>
+<P>
+Contains all the form data sent to the script by the calling form. The NAME
+attribute builds the key and the VALUE attribute is used as the hash value.
+Embperl doesn't care if it is called with the GET or POST method, but there
+may be restrictions on the length of parameters using GET -- not from
+Embperl, but perhaps from the web server, especially if you're using
+Embperl's CGI mode -- it is safer to use POST.
+<P>
+If multiple fields with the same name send to a Embperl page they will put
+in the same hash element and separated be tabs. You can split it up in an
+array, by writting:
+
+<P>
+<PRE> @array = split (/\t/, $fdat{'fieldname'}) ;
+</PRE>
+<P>
+Embperl also supports ENCTYPE multipart/form-data, which is used for file
+uploads. The entry in <CODE>%fdat</CODE> corresponding to the file field
+will be a filehandle, as with CGI.pm. (Embperl uses CGI.pm internally to
+process forms encoded with multipart/form-data.)
+
+<P>
+File upload example:
+
+<P>
+<PRE> HTML page:
+</PRE>
<P>
-<PRE> BEGIN
- {
- $ENV{EMBPERL_SESSION_CLASSES} = "DBIStore SysVSemaphoreLocker" ;
- $ENV{EMBPERL_SESSION_ARGS} = "DataSource=dbi:mysql:session UserName=test" ;
- } ;
+<PRE> <FORM METHOD="POST" ENCTYPE="multipart/form-data">
+ <INPUT TYPE="FILE" NAME="ImageName">
+ </FORM>
</PRE>
<P>
-<PRE> use HTML::Embperl ;
+<PRE> Embperl ACTION:
</PRE>
<P>
-For <STRONG>Solaris</STRONG> it's neccessary to set the <CODE>nsems</CODE> Argument if you use SysVSemaphoreLocker
+<PRE> [- if (defined $fdat{ImageName}) {
+ open FILE, "> /tmp/file.$$";
+ print FILE $buffer
+ while read($fdat{ImageName}, $buffer, 32768);
+ close FILE;
+ }
+ -]
+
+</PRE>
+<P>
+When you have installed CGI.pm 2.46 or above you may also retrieve the
+filename (local filename, as it was on the browser side) and the
+informations provied by the CGI.pm uploadInfo function. To get the filename
+just print out the value of the correspondig <CODE>%fdat</CODE> entry,
+instead of using it as a filehandle. To get the <STRONG>uploadInfo</STRONG> use the fieldname with a dash in front of it:
+<P>
+<PRE> Example:
+</PRE>
<P>
-<PRE> $Apache::Session::SysVSemaphoreLocker::nsems = 16;
+<PRE> # ImageName is the NAME of the field, you must replace it with whatever
+ # name is given in your HTML code
+ Filename: [+ $fdat{ImageName} +] <br>
+ Content-Type: [+ $fdat{-ImageName} -> {'Content-Type'} +] <br>
</PRE>
+<P>
+<STRONG>NOTE:</STRONG> The way <STRONG>uploadInfos</STRONG> are accessed before 1.2b11 are not supported anymore.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_ffld">@ffld</A></H2>
+<P>
+Contains all the field names in the order in which they were sent by the
+browser. This is normally -- but not necessarily -- the order in which they
+appear in your form.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_idat">%idat</A></H2>
+<P>
+Contains all the values from all input tags processed so far.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_udat_only_1_2b1_or_higher_">%udat (only 1.2b1 or higher)</A></H2>
<P>
-You may also put this in the httpd/srm.conf:
+You can use <STRONG>%udat</STRONG> to store per user data. As long as you don't use %udat, nothing happens,
+but as soon as you write anything to %udat, Embperl creates a session id
+and sends it via a cookie to the browser. The data you have written to
+<CODE>%udat</CODE> is stored by Apache::Session. The next time the same
+user request an Embperl page, the browser sends the cookie with the session
+id back and Embperl fill the <CODE>%udat</CODE> hash from Apache::Session
+with just the same values as you have stored for that user. (See also <A href="Embperl.pod.7.html#Session_handling">Session handling</A>)
<P>
-<PRE> PerlSetEnv EMBPERL_SESSION_CLASSES "DBIStore SysVSemaphoreLocker"
- PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=test"
- PerlModule HTML::Embperl ;
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_mdat_only_1_2b2_or_higher_">%mdat (only 1.2b2 or higher)</A></H2>
+<P>
+You can use <STRONG>%mdat</STRONG> to store per module/page data. As long as you don't use %mdat, nothing
+happens, but as soon as you write anything to %mdat, Embperl creates a
+session id and stores the data via Apache::Session. The next time any user
+hits the same Embperl page, Embperl fill the <CODE>%mdat</CODE> hash from
+Apache::Session with just the same values as you have stored within the
+last request to that page. (See also <A href="Embperl.pod.7.html#Session_handling">Session handling</A>)
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_row_col">$row, $col</A></H2>
+<P>
+Row and column counts for use in dynamic tables. (See <A href="Embperl.pod.4.html#HTML_Tags">"HTML tag table"</A>.)
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_maxrow_maxcol">$maxrow, $maxcol</A></H2>
+<P>
+Maxium number of rows or columns to display in a table. To prevent endless
+loops, <CODE>$maxrow</CODE> defaults to 100 and <CODE>$maxcol</CODE> to 10.
+(See <A href="Embperl.pod.4.html#HTML_Tags">"HTML tag table"</A>.)
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_cnt">$cnt</A></H2>
+<P>
+Contains the number of table cells displayed so far. (See <A href="Embperl.pod.4.html#HTML_Tags">"HTML tag table"</A>.)
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_tabmode">$tabmode</A></H2>
+<P>
+Determines how the end of a dynamic table is detected. Tables are always
+limited to the size specified in <CODE>$maxrow</CODE> and $maxcol, but can
+be ended early when the row ($row) and column ($col) variables become
+undefined. <CODE>$tabmode</CODE> operates as follows:
+
+<DL>
+<DT><STRONG><A NAME="item__tabmode">$tabmode = 1</A></STRONG><DD>
+<P>
+End table looping when any one of the expressions in the table row using
+<CODE>$row</CODE> returns undefined. The row containing the undefined
+expression is <STRONG>not</STRONG> displayed. Only those expression are observed which contains an access to
+the varibale $row.
+
+<DT><STRONG>$tabmode = 2</STRONG><DD>
+<P>
+End when an expression with <CODE>$row</CODE> becomes undefined. The row
+containing the undefined expression <STRONG>is</STRONG> displayed.
+
+<DT><STRONG>$tabmode = 4</STRONG><DD>
+<P>
+End when <CODE>$maxrow</CODE> rows have been displayed.
+
+</DL>
+<P>
+<STRONG>end of row</STRONG>
+
+
+
+<DL>
+<DT><STRONG>$tabmode = 16</STRONG><DD>
+<P>
+End table column looping when any one of the expressions in the table
+column using <CODE>$col</CODE> returns undefined. The column containing the
+undefined expression is <STRONG>not</STRONG> displayed. Only those expression are observed which contains an access to
+the varibale $col.
+
+<DT><STRONG>$tabmode = 32</STRONG><DD>
+<P>
+End when an expression with <CODE>$col</CODE> becomes undefined. The column
+containing the undefined expression <STRONG>is</STRONG> displayed.
+
+<DT><STRONG>$tabmode = 64</STRONG><DD>
+<P>
+End when <CODE>$maxcol</CODE> columns have been displayed.
+
+</DL>
+<P>
+The default is <STRONG>17</STRONG>, which is correct for all sort of arrays. You should rarely need to change
+it. The two values can be added together.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_escmode">$escmode</A></H2>
+<P>
+Turn HTML and URL escaping on and off. The default is on ($escmode = 3).
+
+<DL>
+<DT><STRONG><A NAME="item__escmode">$escmode = 3</A></STRONG><DD>
+<P>
+The result of a Perl expression is HTML-escaped (e.g., `>' becomes
+`&gt;') in normal text and URL-escaped (e.g., `&' becomes `%26')
+within of <A href="Embperl.pod.4.html#item_A">A</A>, <CODE>EMBED</CODE>, <CODE>IMG</CODE>, <CODE>IFRAME</CODE>, <CODE>FRAME</CODE> and <CODE>LAYER</CODE> tags.
+
+<DT><STRONG>$escmode = 2</STRONG><DD>
+<P>
+The result of a Perl expression is always URL-escaped (e.g., `&'
+becomes `%26').
+
+<DT><STRONG>$escmode = 1</STRONG><DD>
+<P>
+The result of a Perl expression is always HTML-escaped (e.g., `>'
+becomes `&gt;').
+
+<DT><STRONG>$escmode = 0</STRONG><DD>
+<P>
+No escaping takes place.
+
+</DL>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_req_rec">$req_rec</A></H2>
+<P>
+This variable is only available when running under control of mod_perl. It
+contains the request record needed to access the Apache server API. See <STRONG>perldoc Apache</STRONG> for more information.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="LOG">LOG</A></H2>
+<P>
+This is the filehandle of the Embperl logfile. By writing `print LOG
+``something''' you can add lines to the logfile. NOTE: The logfile line
+should always start with the pid of the current process and continue with a
+four-character signature delimited by a ':', which specifies the log
+reason.
+
+<P>
+Example: print LOG ``[$$]ABCD: your text\n'' ;
+
+<P>
+If you are writing a module for use under Embperl you can say
+
+<P>
+<PRE> tie *LOG, 'HTML::Embperl::Log';
</PRE>
<P>
-<CODE>EMBPERL_SESSION_ARGS</CODE> is a space separated list of name/value pairs, which gives additional
-arguments for Apache::Session classes.
+to get a handle by which you can write to the Embperl logfile.
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="OUT">OUT</A></H2>
+<P>
+This filehandle is tied to Embperl's output stream. Printing to it has the
+same effect as using the [+ ... +] block. (See also <A href="Embperl.pod.3.html#EMBPERL_OPTIONS">optRedirectStdout</A>)
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_param">@param</A></H2>
+<P>
+Will be setup by the <STRONG>'param'</STRONG> parameter of the <STRONG>Execute</STRONG> function. Could be used to pass parameters to an Embperl document and back.
+(see
+<A href="Embperl.pod.2.html#By_calling_HTML_Embperl_Execut">Execute</A>
+for further docs)
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_http_headers_out_only_1_2b10_a">%http_headers_out (only 1.2b10 and above)</A></H2>
+<P>
+You can put any http headers you want to send into this hash. If you set an
+location header Embperl will automaticly set the status to 301 (Redirect).
+Example:
+
+<P>
+<PRE> [- $http_headers_out{'Location'} = "<A HREF="http://www.ecos.de/embperl/"">http://www.ecos.de/embperl/"</A>; -]
+</PRE>
<P>
-<STRONG>NOTE:</STRONG> The above configuration works only with <EM>Embperl</EM> 1.2b11 or above. The way
-<EM>Apache::Session</EM> was used in earlier versions still works, but I have removed the
-documentation to avoid confusion. Changes are, that you don't need to load
-<EM>Apache::Session</EM> anymore on your own and that <EM>Apache::Session 1.00</EM> takes totaly different arguments then <EM>Apache::Session 0.17</EM>.
+see also META HTTP-EQUIV=
<P>
-Now you are able to use the <CODE>%udat</CODE> and <CODE>%mdat</CODE> hashs
-for your user/module sessions. As long as you don't touch
-<CODE>%udat</CODE> or <CODE>%mdat</CODE> Embperl will not create any
-session, also Apache::Session is loaded. As soon as you store any value to
-%udat, Embperl will create a new session and send a cookie to the browser
-to maintain it's id, while the data is stored by Apache::Session. (Further
-version may also be able to use URL rewriting for storing the id). When you
-store data to <CODE>%mdat</CODE> Embperl will store the data via
-Apache::Session and retrieves it when the next request comes to the same
-page.
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_optXXX_dbgXXX">$optXXX $dbgXXX</A></H2>
+<P>
+All options (see <A href="Embperl.pod.3.html#EMBPERL_OPTIONS">EMBPERL_OPTIONS</A>) and all debugging flags (see <A href="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A>) can be read and set by the corresponding variables.
+
+<P>
+<PRE> Example:
+</PRE>
+<P>
+<PRE> [- $optRawInput = 1 -] # Turn the RawInput option on
+
+ Now write something here
+</PRE>
+<P>
+<PRE> [- $optRawInput = 0 -] # Turn the RawInput option off again
+</PRE>
+<P>
+<PRE> [+ $dbgCmd +] # Output the state of the dbgCmd flag
+</PRE>
+<P>
+There are a few exceptions, where the variables can only be read. Setting
+of such options must be done via the config-files. Read-only variables are:
+
+<DL>
+<DT><STRONG><A NAME="item__optDisableVarCleanup">$optDisableVarCleanup</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optSafeNamespace">$optSafeNamespace</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optOpcodeMask">$optOpcodeMask</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optDisableChdir">$optDisableChdir</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optEarlyHttpHeader">$optEarlyHttpHeader</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optDisableFormData">$optDisableFormData</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optAllFormData">$optAllFormData</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optRedirectStdout">$optRedirectStdout</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optAllowZeroFilesize">$optAllowZeroFilesize</A></STRONG><DD>
+<DT><STRONG><A NAME="item__optKeepSrcInMemory">$optKeepSrcInMemory</A></STRONG><DD>
+</DL>
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="_CLEANUP">%CLEANUP</A></H2>
+<P>
+Embperl cleanups up only variables with are defined within the Embperl
+page. If you want Embperl to cleanup addtional variables you can add them
+to the hash %CLEANUP, with the key set to the variable name and the value
+set to one. The other way round you could prevent Embperl from cleaning up
+some variables, by adding them to this hash, with a values of zero.
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.5.html">PREV (Predefined variables)</a>] [<a href="Embperl.pod.7.html">NEXT ((Safe-)Namespaces and opcode restrictions)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.5.html">PREV (Variable scope and cleanup)</a>] [<a href="Embperl.pod.7.html">NEXT (Session handling)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.8 +43 -70 modperl-site/embperl/Embperl.pod.7.html
Index: Embperl.pod.7.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.7.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- Embperl.pod.7.html 1999/05/10 20:37:00 1.7
+++ Embperl.pod.7.html 2000/02/20 20:29:32 1.8
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Namespaces and opcode restrictions</TITLE>
+<TITLE>Session handling</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</a></strong></h1>
+<A NAME="Session_handling">Session handling</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,97 +16,70 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.6.html">PREV (Session handling)</a>] [<a href="Embperl.pod.8.html">NEXT (Utility Functions)</a>] <br><hr>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.6.html">PREV (Predefined variables)</a>] [<a href="Embperl.pod.8.html">NEXT ((Safe-)Namespaces and opcode restrictions)</a>] <br><hr>
<P>
-Since most web servers will contain more than one document, it is necessary
-to protect the documents against each other. Embperl does this by using
-Perl namespaces. By default, Embperl executes every document in its own
-namespace (package). This will prevent documents from accidentally
-overriding the other's data. You can change this behavior (or simply the
-package name) with the configuration directive
-<STRONG>EMBPERL_PACKAGE</STRONG>. NOTE: By explicitly specifying a package name, you can access data that
-is used by another document.
+From 1.2b1 and higher Embperl is able to handle per user sessions for you.
+You can store any data in the <EM>%udat</EM> hash and if the same user request again an Embperl document, you will see
+the same values in that hash again.
<P>
-If Embperl is used by more then one person, it may be neccessary to really
-protect documents from each other. To do this, Embperl gives you the option
-of using safe namespaces. Each document runs in its own package and can't
-access anything outside of this package. (See the documentation of Safe.pm
-for a more detailed discussion of safe namespaces.)
+From 1.2b2 and higher Embperl is able to handle per module/page persitent
+data for you. You can store any data in the <EM>%mdat</EM> hash and if any request comes to the same Embperl document, you will see
+the same values in that hash again.
<P>
-To make a document run in a safe namespace, simply add
-<STRONG>optSafeNamespace</STRONG> to <STRONG>EMBPERL_OPTIONS</STRONG>. The default package name used is the same as in normal operation and can
-be changed with
-<STRONG>EMBPERL_PACKAGE</STRONG>. NOTE: From the perspective of the document being executed, the code is
-running in the package <STRONG>main</STRONG>!
+To configure <EM>Embperl</EM> to do session management for you, you must have installed <EM>Apache::Session</EM> (<STRONG>1.00 or higher</STRONG>) and tell Embperl which storage and locker classes you would like to use
+for
+<EM>Apache::Session</EM>. This is done by setting the environement variable
+<CODE>EMBPERL_SESSION_CLASSES</CODE>. You may have a <STRONG>startup.pl</STRONG> for your httpd which looks like this:
<P>
-A second option to make Embperl more secure is the use of the opcode
-restriction mask. Before you can use the opcode mask, you must set up a
-safe compartment.
-
-<P>
-<PRE> B<$cp = HTML::Embperl::AddCompartment($name);>
+<PRE> BEGIN
+ {
+ $ENV{EMBPERL_SESSION_CLASSES} = "DBIStore SysVSemaphoreLocker" ;
+ $ENV{EMBPERL_SESSION_ARGS} = "DataSource=dbi:mysql:session UserName=test" ;
+ } ;
</PRE>
-<P>
-This will create a new compartment with a default opcode mask and the name
-$name. (The name is used later to tell Embperl which compartment to use.)
-Now you can change the operator mask. For example:
-
<P>
-<PRE> B<$cp->deny(':base_loop');>
+<PRE> use HTML::Embperl ;
</PRE>
<P>
-In your configuration you must set the option <STRONG>optOpcodeMask</STRONG> in
-<STRONG>EMBPERL_OPTIONS</STRONG> and specify from which compartment the opcode mask should be taken by
-setting <STRONG>EMBPERL_COMPARTMENT</STRONG>.
+For <STRONG>Solaris</STRONG> it's neccessary to set the <CODE>nsems</CODE> Argument if you use SysVSemaphoreLocker
-<P>
-<PRE> Example (for use with mod_perl):
-</PRE>
-<P>
-<PRE> B<srm.conf:>
-</PRE>
<P>
-<PRE> PerlScript startup.pl
+<PRE> $Apache::Session::SysVSemaphoreLocker::nsems = 16;
</PRE>
<P>
-<PRE> SetEnv EMBPERL_DEBUG 2285
-</PRE>
-<P>
-<PRE> Alias /embperl /path/to/embperl/eg
-</PRE>
-<P>
-<PRE> <Location /embperl/x>
- SetHandler perl-script
- PerlHandler HTML::Embperl
- Options ExecCGI
- PerlSetEnv EMBPERL_OPTIONS 12
- PerlSetEnv EMBPERL_COMPARTMENT test
- </Location>
-</PRE>
-<P>
-<PRE> B<startup.pl:>
-</PRE>
+You may also put this in the httpd/srm.conf:
+
<P>
-<PRE> $cp = HTML::Embperl::AddCompartment('test');
- $cp->deny(':base_loop');
+<PRE> PerlSetEnv EMBPERL_SESSION_CLASSES "DBIStore SysVSemaphoreLocker"
+ PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=test"
+ PerlModule HTML::Embperl ;
</PRE>
<P>
-This will execute the file startup.pl on server startup. startup.pl sets up
-a compartment named `test', which will have a default opcode mask and
-additionaly, will have loops disabled. Code will be executed in a safe
-namespace.
+<CODE>EMBPERL_SESSION_ARGS</CODE> is a space separated list of name/value pairs, which gives additional
+arguments for Apache::Session classes.
<P>
-NOTE: The package name from the compartment is <STRONG>NOT</STRONG> used!
+<STRONG>NOTE:</STRONG> The above configuration works only with <EM>Embperl</EM> 1.2b11 or above. The way
+<EM>Apache::Session</EM> was used in earlier versions still works, but I have removed the
+documentation to avoid confusion. Changes are, that you don't need to load
+<EM>Apache::Session</EM> anymore on your own and that <EM>Apache::Session 1.00</EM> takes totaly different arguments then <EM>Apache::Session 0.17</EM>.
<P>
-Look at the documentation of Safe.pm and Opcode.pm for more detailed
-information on how to set opcode masks.
+Now you are able to use the <CODE>%udat</CODE> and <CODE>%mdat</CODE> hashs
+for your user/module sessions. As long as you don't touch
+<CODE>%udat</CODE> or <CODE>%mdat</CODE> Embperl will not create any
+session, also Apache::Session is loaded. As soon as you store any value to
+%udat, Embperl will create a new session and send a cookie to the browser
+to maintain it's id, while the data is stored by Apache::Session. (Further
+version may also be able to use URL rewriting for storing the id). When you
+store data to <CODE>%mdat</CODE> Embperl will store the data via
+Apache::Session and retrieves it when the next request comes to the same
+page.
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.6.html">PREV (Session handling)</a>] [<a href="Embperl.pod.8.html">NEXT (Utility Functions)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.6.html">PREV (Predefined variables)</a>] [<a href="Embperl.pod.8.html">NEXT ((Safe-)Namespaces and opcode restrictions)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.7 +67 -65 modperl-site/embperl/Embperl.pod.8.html
Index: Embperl.pod.8.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.8.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Embperl.pod.8.html 1999/10/13 05:48:39 1.6
+++ Embperl.pod.8.html 2000/02/20 20:29:32 1.7
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Utility Functions</TITLE>
+<TITLE>Namespaces and opcode restrictions</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Utility_Functions">Utility Functions</a></strong></h1>
+<A NAME="_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,95 +16,97 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.7.html">PREV ((Safe-)Namespaces and opcode restrictions)</a>] [<a href="Embperl.pod.9.html">NEXT (Input/Output Functions)</a>] <br> <UL>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.7.html">PREV (Session handling)</a>] [<a href="Embperl.pod.9.html">NEXT (Utility Functions)</a>] <br><hr>
+<P>
+Since most web servers will contain more than one document, it is necessary
+to protect the documents against each other. Embperl does this by using
+Perl namespaces. By default, Embperl executes every document in its own
+namespace (package). This will prevent documents from accidentally
+overriding the other's data. You can change this behavior (or simply the
+package name) with the configuration directive
+<STRONG>EMBPERL_PACKAGE</STRONG>. NOTE: By explicitly specifying a package name, you can access data that
+is used by another document.
- <LI><A href="Embperl.pod.8.html#AddCompartment_Name_">AddCompartment($Name)</A>
- <LI><A href="Embperl.pod.8.html#MailFormTo_MailTo_Subject_R">MailFormTo($MailTo, $Subject, $ReturnField)</A>
- <LI><A href="Embperl.pod.8.html#exit">exit</A>
- </UL>
-<hr>
<P>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="AddCompartment_Name_">AddCompartment($Name)</A></H2>
+If Embperl is used by more then one person, it may be neccessary to really
+protect documents from each other. To do this, Embperl gives you the option
+of using safe namespaces. Each document runs in its own package and can't
+access anything outside of this package. (See the documentation of Safe.pm
+for a more detailed discussion of safe namespaces.)
+
<P>
-Adds a compartment for use with Embperl. Embperl only uses the opcode mask
-from it, not the package name. AddCompartment returns the newly- created
-compartment so you can allow or deny certain opcodes. See the Safe.pm
-documentation for details of setting up a compartment. See the chapter
-about <A href="Embperl.pod.7.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> for details on how Embperl uses compartments.
+To make a document run in a safe namespace, simply add
+<STRONG>optSafeNamespace</STRONG> to <STRONG>EMBPERL_OPTIONS</STRONG>. The default package name used is the same as in normal operation and can
+be changed with
+<STRONG>EMBPERL_PACKAGE</STRONG>. NOTE: From the perspective of the document being executed, the code is
+running in the package <STRONG>main</STRONG>!
<P>
-Example:
+A second option to make Embperl more secure is the use of the opcode
+restriction mask. Before you can use the opcode mask, you must set up a
+safe compartment.
<P>
-<PRE> $cp = HTML::Embperl::AddCompartment('TEST');
- $cp->deny(':base_loop');
+<PRE> B<$cp = HTML::Embperl::AddCompartment($name);>
</PRE>
-<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="MailFormTo_MailTo_Subject_R">MailFormTo($MailTo, $Subject, $ReturnField)</A></H2>
<P>
-Sends the content of the hash <CODE>%fdat</CODE> in the order specified by
-@ffld to the given <STRONG>$MailTo</STRONG> addressee, with a subject of <STRONG>$Subject</STRONG>. If you specify <CODE>$ReturnField</CODE> the value of that formfield will
-be used as <STRONG>Return-Path</STRONG>. Usually, this will be the field where the user enters his e-mail address
-in the form.
+This will create a new compartment with a default opcode mask and the name
+$name. (The name is used later to tell Embperl which compartment to use.)
+Now you can change the operator mask. For example:
+<P>
+<PRE> B<$cp->deny(':base_loop');>
+</PRE>
<P>
-If you specifiy the following example code as the action in your form
+In your configuration you must set the option <STRONG>optOpcodeMask</STRONG> in
+<STRONG>EMBPERL_OPTIONS</STRONG> and specify from which compartment the opcode mask should be taken by
+setting <STRONG>EMBPERL_COMPARTMENT</STRONG>.
<P>
-<PRE> <FORM ACTION="x/feedback.htm" METHOD="POST"
- ENCTYPE="application/x-www-form-urlencoded">
+<PRE> Example (for use with mod_perl):
</PRE>
<P>
-The content of the form will be mailed to the given e-mail address.
-
+<PRE> B<srm.conf:>
+</PRE>
<P>
-MailFormTo uses <A href="Embperl.pod.2.html#EMBPERL_MAILHOST">EMBPERL_MAILHOST</A> as SMTP server or <STRONG>localhost</STRONG>
-if non given.
-
+<PRE> PerlScript startup.pl
+</PRE>
<P>
-Example:
-
+<PRE> SetEnv EMBPERL_DEBUG 2285
+</PRE>
<P>
-<PRE> <HTML>
- <HEAD>
- <TITLE>Feedback</TITLE>
- </HEAD>
- <BODY>
- [- MailFormTo('webmaster@domain.xy',
- 'Mail from WWW Form', 'email') -]
- Your data has been sccesfully sent!
- </BODY>
- </HTML>
+<PRE> Alias /embperl /path/to/embperl/eg
</PRE>
<P>
-This will send a mail with all fields of the form to <A
-HREF="mailto:webmaster@domain.xy,">webmaster@domain.xy,</A> with the
-Subject 'Mail form WWW Form' and will set the Return-Path of the mail to
-the address which was entered in the field with the name 'email'.
-
+<PRE> <Location /embperl/x>
+ SetHandler perl-script
+ PerlHandler HTML::Embperl
+ Options ExecCGI
+ PerlSetEnv EMBPERL_OPTIONS 12
+ PerlSetEnv EMBPERL_COMPARTMENT test
+ </Location>
+</PRE>
<P>
-<STRONG>NOTE:</STRONG> You must have Net::SMTP (from the libnet package) installed to use this
-function.
-
+<PRE> B<startup.pl:>
+</PRE>
+<P>
+<PRE> $cp = HTML::Embperl::AddCompartment('test');
+ $cp->deny(':base_loop');
+</PRE>
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="exit">exit</A></H2>
+This will execute the file startup.pl on server startup. startup.pl sets up
+a compartment named `test', which will have a default opcode mask and
+additionaly, will have loops disabled. Code will be executed in a safe
+namespace.
+
<P>
-<STRONG>exit</STRONG> will override the normal Perl exit in every Embperl document. Calling exit
-will immediately stop any further processing of that file and send the
-already-done work to the output/browser.
+NOTE: The package name from the compartment is <STRONG>NOT</STRONG> used!
<P>
-<STRONG>NOTE 1:</STRONG> If you are inside of an Execute, Embperl will only exit this Execute, but
-the file which called the file containing the exit with Execute will
-continue.
-
-<STRONG>NOTE 2:</STRONG> If you write a module which should work with Embperl under mod_perl, you
-must use Apache::exit instead of the normal Perl exit (just like always
-when running under mod_perl).
+Look at the documentation of Safe.pm and Opcode.pm for more detailed
+information on how to set opcode masks.
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.7.html">PREV ((Safe-)Namespaces and opcode restrictions)</a>] [<a href="Embperl.pod.9.html">NEXT (Input/Output Functions)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.7.html">PREV (Session handling)</a>] [<a href="Embperl.pod.9.html">NEXT (Utility Functions)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.6 +69 -57 modperl-site/embperl/Embperl.pod.9.html
Index: Embperl.pod.9.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.9.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Embperl.pod.9.html 1999/05/10 20:37:01 1.5
+++ Embperl.pod.9.html 2000/02/20 20:29:32 1.6
@@ -1,6 +1,6 @@
<HTML>
<HEAD>
-<TITLE>Input/Output Functions</TITLE>
+<TITLE>Utility Functions</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
</HEAD>
@@ -8,7 +8,7 @@
<blockquote>
<blockquote>
<H1><strong>
-<A NAME="Input_Output_Functions">Input/Output Functions</a></strong></h1>
+<A NAME="Utility_Functions">Utility Functions</a></strong></h1>
</blockquote>
</blockquote>
@@ -16,83 +16,95 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.8.html">PREV (Utility Functions)</a>] [<a href="Embperl.pod.10.html">NEXT (Inside Embperl - How the embedded Perl code is actually processed)</a>] <br> <UL>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.8.html">PREV ((Safe-)Namespaces and opcode restrictions)</a>] [<a href="Embperl.pod.10.html">NEXT (Input/Output Functions)</a>] <br> <UL>
- <LI><A href="Embperl.pod.9.html#ProxyInput_r_in_mtime_sr">ProxyInput ($r, $in, $mtime, $src, $dest)</A>
- <LI><A href="Embperl.pod.9.html#LogOutput_r_out_basepath_">LogOutput ($r, $out, $basepath)</A>
+ <LI><A href="Embperl.pod.9.html#AddCompartment_Name_">AddCompartment($Name)</A>
+ <LI><A href="Embperl.pod.9.html#MailFormTo_MailTo_Subject_R">MailFormTo($MailTo, $Subject, $ReturnField)</A>
+ <LI><A href="Embperl.pod.9.html#exit">exit</A>
</UL>
<hr>
<P>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="ProxyInput_r_in_mtime_sr">ProxyInput ($r, $in, $mtime, $src, $dest)</A></H2>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="AddCompartment_Name_">AddCompartment($Name)</A></H2>
<P>
-<PRE> B<USAGE in srm.conf:>
-</PRE>
+Adds a compartment for use with Embperl. Embperl only uses the opcode mask
+from it, not the package name. AddCompartment returns the newly- created
+compartment so you can allow or deny certain opcodes. See the Safe.pm
+documentation for details of setting up a compartment. See the chapter
+about <A href="Embperl.pod.8.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> for details on how Embperl uses compartments.
+
<P>
-<PRE> <Location /embperl/ifunc>
- SetHandler perl-script
- PerlHandler HTML::Embperl
- Options ExecCGI
- PerlSetEnv EMBPERL_INPUT_FUNC "ProxyInput, /embperl/ifunc, <A HREF="http://otherhost/otherpath"">http://otherhost/otherpath"</A>;
- </Location>
+Example:
+
+<P>
+<PRE> $cp = HTML::Embperl::AddCompartment('TEST');
+ $cp->deny(':base_loop');
</PRE>
<P>
-This input function will request the source from another URL instead of
-reading it from the disk. In the above USAGE Example, a request to
-/embperl/ifunc/foo.html, will first fetch the URL <A
-HREF="http://otherhost/otherpath/foo.html,">http://otherhost/otherpath/foo.html,</A>
-and then it will process this document by Embperl and then it will send it
-to the browser.
-
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="MailFormTo_MailTo_Subject_R">MailFormTo($MailTo, $Subject, $ReturnField)</A></H2>
<P>
-This could be used to process documents by mod_include <STRONG>and</STRONG> Embperl, so in one document there can be both Server-Side Includes and
-Embperl Commands.
+Sends the content of the hash <CODE>%fdat</CODE> in the order specified by
+@ffld to the given <STRONG>$MailTo</STRONG> addressee, with a subject of <STRONG>$Subject</STRONG>. If you specify <CODE>$ReturnField</CODE> the value of that formfield will
+be used as <STRONG>Return-Path</STRONG>. Usually, this will be the field where the user enters his e-mail address
+in the form.
<P>
-<PRE> Example B<srm.conf> for B<SSI> and B<Embperl>:
-</PRE>
+If you specifiy the following example code as the action in your form
+
<P>
-<PRE> <Location /embperl>
- SetHandler perl-script
- PerlHandler HTML::Embperl
- Options ExecCGI
- PerlSetEnv EMBPERL_INPUT_FUNC "ProxyInput, /embperl, <A HREF="http://localhost/src"">http://localhost/src"</A>;
- </Location>
+<PRE> <FORM ACTION="x/feedback.htm" METHOD="POST"
+ ENCTYPE="application/x-www-form-urlencoded">
</PRE>
<P>
-<PRE> <Location /src>
- SetHandler server-parsed
- Options +Includes
- </Location>
-</PRE>
+The content of the form will be mailed to the given e-mail address.
+
<P>
-The source files must be in the location /src, but they will be requested
-via the URI /embperl. Every request to /embperl/foo.html will do a
-proxy-request to /src/foo.html. The file /src/foo.html will be processed by
-mod_include and then sent to Embperl, where it can be processed by Embperl
-before being sent to the browser. It would be also possible to use two
-httpd's on different ports. In this configuration, the source and the URI
-location could be the same.
+MailFormTo uses <A href="Embperl.pod.3.html#EMBPERL_MAILHOST">EMBPERL_MAILHOST</A> as SMTP server or <STRONG>localhost</STRONG>
+if non given.
<P>
-<HR>
-<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="LogOutput_r_out_basepath_">LogOutput ($r, $out, $basepath)</A></H2>
+Example:
+
<P>
-<PRE> B<USAGE in srm.conf:>
+<PRE> <HTML>
+ <HEAD>
+ <TITLE>Feedback</TITLE>
+ </HEAD>
+ <BODY>
+ [- MailFormTo('webmaster@domain.xy',
+ 'Mail from WWW Form', 'email') -]
+ Your data has been sccesfully sent!
+ </BODY>
+ </HTML>
</PRE>
<P>
-<PRE> <Location /embperl/ofunc>
- SetHandler perl-script
- PerlHandler HTML::Embperl
- Options ExecCGI
- PerlSetEnv EMBPERL_OUTPUT_FUNC "LogOutput, /usr/msrc/embperl/test/tmp/log.out"
- </Location>
-</PRE>
+This will send a mail with all fields of the form to <A
+HREF="mailto:webmaster@domain.xy,">webmaster@domain.xy,</A> with the
+Subject 'Mail form WWW Form' and will set the Return-Path of the mail to
+the address which was entered in the field with the name 'email'.
+
+<P>
+<STRONG>NOTE:</STRONG> You must have Net::SMTP (from the libnet package) installed to use this
+function.
+
+<P>
+<HR>
+<H2><img src="sq.gif" width="16" height="16" alt="-"> <A NAME="exit">exit</A></H2>
<P>
-LogOutput is a custom output function. It sends the output to the browser <STRONG>and</STRONG>
-writes the output to a unique file. The filename has the the form
-``$basepath.$$.$LogOutputFileno''.
+<STRONG>exit</STRONG> will override the normal Perl exit in every Embperl document. Calling exit
+will immediately stop any further processing of that file and send the
+already-done work to the output/browser.
+
+<P>
+<STRONG>NOTE 1:</STRONG> If you are inside of an Execute, Embperl will only exit this Execute, but
+the file which called the file containing the exit with Execute will
+continue.
+
+<STRONG>NOTE 2:</STRONG> If you write a module which should work with Embperl under mod_perl, you
+must use Apache::exit instead of the normal Perl exit (just like always
+when running under mod_perl).
-<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.8.html">PREV (Utility Functions)</a>] [<a href="Embperl.pod.10.html">NEXT (Inside Embperl - How the embedded Perl code is actually processed)</a>] <br>
+<p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.8.html">PREV ((Safe-)Namespaces and opcode restrictions)</a>] [<a href="Embperl.pod.10.html">NEXT (Input/Output Functions)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.20 +92 -91 modperl-site/embperl/Embperl.pod.cont.html
Index: Embperl.pod.cont.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Embperl.pod.cont.html,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- Embperl.pod.cont.html 2000/02/11 22:34:16 1.19
+++ Embperl.pod.cont.html 2000/02/20 20:29:32 1.20
@@ -16,7 +16,7 @@
<BR CLEAR=LEFT>
<blockquote>
<blockquote>
-[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.1.html">NEXT (Operating-Modes)</a>] <br><HTML>
+[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.1.html">NEXT (DESCRIPTION)</a>] <br><HTML>
<HEAD>
<TITLE>Documentation - Content</TITLE>
<LINK REV="made" HREF="mailto:root@venus.gr.ecos.de">
@@ -28,138 +28,139 @@
<UL>
- <LI><A href="Embperl.pod.1.html#Operating_Modes">Operating-Modes</A>
+ <LI><A href="Embperl.pod.1.html#DESCRIPTION">DESCRIPTION</A>
+ <LI><A href="Embperl.pod.2.html#Operating_Modes">Operating-Modes</A>
<UL>
- <LI><A href="Embperl.pod.1.html#Offline">Offline</A>
- <LI><A href="Embperl.pod.1.html#As_a_CGI_script">As a CGI script</A>
- <LI><A href="Embperl.pod.1.html#From_mod_perl_Apache_httpd_">From mod_perl (Apache httpd)</A>
- <LI><A href="Embperl.pod.1.html#By_calling_HTML_Embperl_Execut">By calling HTML::Embperl::Execute (\%param)</A>
- <LI><A href="Embperl.pod.1.html#Helper_functions_for_Execute">Helper functions for Execute</A>
- <LI><A href="Embperl.pod.1.html#EXAMPLES_for_Execute_">EXAMPLES for Execute:</A>
+ <LI><A href="Embperl.pod.2.html#Offline">Offline</A>
+ <LI><A href="Embperl.pod.2.html#As_a_CGI_script">As a CGI script</A>
+ <LI><A href="Embperl.pod.2.html#From_mod_perl_Apache_httpd_">From mod_perl (Apache httpd)</A>
+ <LI><A href="Embperl.pod.2.html#By_calling_HTML_Embperl_Execut">By calling HTML::Embperl::Execute (\%param)</A>
+ <LI><A href="Embperl.pod.2.html#Helper_functions_for_Execute">Helper functions for Execute</A>
+ <LI><A href="Embperl.pod.2.html#EXAMPLES_for_Execute_">EXAMPLES for Execute:</A>
</UL>
- <LI><A href="Embperl.pod.2.html#Runtime_configuration">Runtime configuration</A>
+ <LI><A href="Embperl.pod.3.html#Runtime_configuration">Runtime configuration</A>
<UL>
- <LI><A href="Embperl.pod.2.html#EMBPERL_FILESMATCH">EMBPERL_FILESMATCH</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_ALLOW_only_1_2b10_and_a">EMBPERL_ALLOW (only 1.2b10 and above)</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_PATH_1_3b1_and_above_">EMBPERL_PATH (1.3b1 and above)</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COMPARTMENT">EMBPERL_COMPARTMENT</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_ESCMODE">EMBPERL_ESCMODE</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_LOG">EMBPERL_LOG</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_PACKAGE">EMBPERL_PACKAGE</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_OPTIONS">EMBPERL_OPTIONS</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_INPUT_FUNC">EMBPERL_INPUT_FUNC</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_OUTPUT_FUNC">EMBPERL_OUTPUT_FUNC</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_MAILHOST">EMBPERL_MAILHOST</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_MAILFROM">EMBPERL_MAILFROM </A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_MAILDEBUG">EMBPERL_MAILDEBUG </A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_MAIL_ERRORS_TO">EMBPERL_MAIL_ERRORS_TO</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COOKIE_NAME">EMBPERL_COOKIE_NAME</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COOKIE_DOMAIN">EMBPERL_COOKIE_DOMAIN</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COOKIE_PATH">EMBPERL_COOKIE_PATH</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_COOKIE_EXPIRES">EMBPERL_COOKIE_EXPIRES</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_SESSION_CLASSES">EMBPERL_SESSION_CLASSES</A>
- <LI><A href="Embperl.pod.2.html#EMBPERL_SESSION_ARGS">EMBPERL_SESSION_ARGS</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_FILESMATCH">EMBPERL_FILESMATCH</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_ALLOW_only_1_2b10_and_a">EMBPERL_ALLOW (only 1.2b10 and above)</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_PATH_1_3b1_and_above_">EMBPERL_PATH (1.3b1 and above)</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COMPARTMENT">EMBPERL_COMPARTMENT</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_ESCMODE">EMBPERL_ESCMODE</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_LOG">EMBPERL_LOG</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_PACKAGE">EMBPERL_PACKAGE</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_VIRTLOG">EMBPERL_VIRTLOG</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_OPTIONS">EMBPERL_OPTIONS</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_INPUT_FUNC">EMBPERL_INPUT_FUNC</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_OUTPUT_FUNC">EMBPERL_OUTPUT_FUNC</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_MAILHOST">EMBPERL_MAILHOST</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_MAILFROM">EMBPERL_MAILFROM </A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_MAILDEBUG">EMBPERL_MAILDEBUG </A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_MAIL_ERRORS_TO">EMBPERL_MAIL_ERRORS_TO</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COOKIE_NAME">EMBPERL_COOKIE_NAME</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COOKIE_DOMAIN">EMBPERL_COOKIE_DOMAIN</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COOKIE_PATH">EMBPERL_COOKIE_PATH</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_COOKIE_EXPIRES">EMBPERL_COOKIE_EXPIRES</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_SESSION_CLASSES">EMBPERL_SESSION_CLASSES</A>
+ <LI><A href="Embperl.pod.3.html#EMBPERL_SESSION_ARGS">EMBPERL_SESSION_ARGS</A>
</UL>
- <LI><A href="Embperl.pod.3.html#SYNTAX">SYNTAX</A>
+ <LI><A href="Embperl.pod.4.html#SYNTAX">SYNTAX</A>
<UL>
- <LI><A href="Embperl.pod.3.html#_Perl_code_">[+ Perl code +]</A>
- <LI><A href="Embperl.pod.3.html#_Perl_code_">[- Perl code -]</A>
- <LI><A href="Embperl.pod.3.html#_Perl_Code_">[! Perl Code !]</A>
- <LI><A href="Embperl.pod.3.html#_Perl_code_">[* Perl code *]</A>
- <LI><A href="Embperl.pod.3.html#_Some_Text_Comments_">[# Some Text #] (Comments)</A>
- <LI><A href="Embperl.pod.3.html#_Cmd_Arg_Meta_Commands_">[$ Cmd Arg $] (Meta-Commands)</A>
- <LI><A href="Embperl.pod.3.html#HTML_Tags">HTML Tags</A>
+ <LI><A href="Embperl.pod.4.html#_Perl_code_">[+ Perl code +]</A>
+ <LI><A href="Embperl.pod.4.html#_Perl_code_">[- Perl code -]</A>
+ <LI><A href="Embperl.pod.4.html#_Perl_Code_">[! Perl Code !]</A>
+ <LI><A href="Embperl.pod.4.html#_Perl_code_">[* Perl code *]</A>
+ <LI><A href="Embperl.pod.4.html#_Some_Text_Comments_">[# Some Text #] (Comments)</A>
+ <LI><A href="Embperl.pod.4.html#_Cmd_Arg_Meta_Commands_">[$ Cmd Arg $] (Meta-Commands)</A>
+ <LI><A href="Embperl.pod.4.html#HTML_Tags">HTML Tags</A>
</UL>
- <LI><A href="Embperl.pod.4.html#Variable_scope_and_cleanup">Variable scope and cleanup</A>
- <LI><A href="Embperl.pod.5.html#Predefined_variables">Predefined variables</A>
+ <LI><A href="Embperl.pod.5.html#Variable_scope_and_cleanup">Variable scope and cleanup</A>
+ <LI><A href="Embperl.pod.6.html#Predefined_variables">Predefined variables</A>
<UL>
- <LI><A href="Embperl.pod.5.html#_ENV">%ENV</A>
- <LI><A href="Embperl.pod.5.html#_fdat">%fdat</A>
- <LI><A href="Embperl.pod.5.html#_ffld">@ffld</A>
- <LI><A href="Embperl.pod.5.html#_idat">%idat</A>
- <LI><A href="Embperl.pod.5.html#_udat_only_1_2b1_or_higher_">%udat (only 1.2b1 or higher)</A>
- <LI><A href="Embperl.pod.5.html#_mdat_only_1_2b2_or_higher_">%mdat (only 1.2b2 or higher)</A>
- <LI><A href="Embperl.pod.5.html#_row_col">$row, $col</A>
- <LI><A href="Embperl.pod.5.html#_maxrow_maxcol">$maxrow, $maxcol</A>
- <LI><A href="Embperl.pod.5.html#_cnt">$cnt</A>
- <LI><A href="Embperl.pod.5.html#_tabmode">$tabmode</A>
- <LI><A href="Embperl.pod.5.html#_escmode">$escmode</A>
- <LI><A href="Embperl.pod.5.html#_req_rec">$req_rec</A>
- <LI><A href="Embperl.pod.5.html#LOG">LOG</A>
- <LI><A href="Embperl.pod.5.html#OUT">OUT</A>
- <LI><A href="Embperl.pod.5.html#_param">@param</A>
- <LI><A href="Embperl.pod.5.html#_http_headers_out_only_1_2b10_a">%http_headers_out (only 1.2b10 and above)</A>
- <LI><A href="Embperl.pod.5.html#_optXXX_dbgXXX">$optXXX $dbgXXX</A>
- <LI><A href="Embperl.pod.5.html#_CLEANUP">%CLEANUP</A>
+ <LI><A href="Embperl.pod.6.html#_ENV">%ENV</A>
+ <LI><A href="Embperl.pod.6.html#_fdat">%fdat</A>
+ <LI><A href="Embperl.pod.6.html#_ffld">@ffld</A>
+ <LI><A href="Embperl.pod.6.html#_idat">%idat</A>
+ <LI><A href="Embperl.pod.6.html#_udat_only_1_2b1_or_higher_">%udat (only 1.2b1 or higher)</A>
+ <LI><A href="Embperl.pod.6.html#_mdat_only_1_2b2_or_higher_">%mdat (only 1.2b2 or higher)</A>
+ <LI><A href="Embperl.pod.6.html#_row_col">$row, $col</A>
+ <LI><A href="Embperl.pod.6.html#_maxrow_maxcol">$maxrow, $maxcol</A>
+ <LI><A href="Embperl.pod.6.html#_cnt">$cnt</A>
+ <LI><A href="Embperl.pod.6.html#_tabmode">$tabmode</A>
+ <LI><A href="Embperl.pod.6.html#_escmode">$escmode</A>
+ <LI><A href="Embperl.pod.6.html#_req_rec">$req_rec</A>
+ <LI><A href="Embperl.pod.6.html#LOG">LOG</A>
+ <LI><A href="Embperl.pod.6.html#OUT">OUT</A>
+ <LI><A href="Embperl.pod.6.html#_param">@param</A>
+ <LI><A href="Embperl.pod.6.html#_http_headers_out_only_1_2b10_a">%http_headers_out (only 1.2b10 and above)</A>
+ <LI><A href="Embperl.pod.6.html#_optXXX_dbgXXX">$optXXX $dbgXXX</A>
+ <LI><A href="Embperl.pod.6.html#_CLEANUP">%CLEANUP</A>
</UL>
- <LI><A href="Embperl.pod.6.html#Session_handling">Session handling</A>
- <LI><A href="Embperl.pod.7.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A>
- <LI><A href="Embperl.pod.8.html#Utility_Functions">Utility Functions</A>
+ <LI><A href="Embperl.pod.7.html#Session_handling">Session handling</A>
+ <LI><A href="Embperl.pod.8.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A>
+ <LI><A href="Embperl.pod.9.html#Utility_Functions">Utility Functions</A>
<UL>
- <LI><A href="Embperl.pod.8.html#AddCompartment_Name_">AddCompartment($Name)</A>
- <LI><A href="Embperl.pod.8.html#MailFormTo_MailTo_Subject_R">MailFormTo($MailTo, $Subject, $ReturnField)</A>
- <LI><A href="Embperl.pod.8.html#exit">exit</A>
+ <LI><A href="Embperl.pod.9.html#AddCompartment_Name_">AddCompartment($Name)</A>
+ <LI><A href="Embperl.pod.9.html#MailFormTo_MailTo_Subject_R">MailFormTo($MailTo, $Subject, $ReturnField)</A>
+ <LI><A href="Embperl.pod.9.html#exit">exit</A>
</UL>
- <LI><A href="Embperl.pod.9.html#Input_Output_Functions">Input/Output Functions</A>
+ <LI><A href="Embperl.pod.10.html#Input_Output_Functions">Input/Output Functions</A>
<UL>
- <LI><A href="Embperl.pod.9.html#ProxyInput_r_in_mtime_sr">ProxyInput ($r, $in, $mtime, $src, $dest)</A>
- <LI><A href="Embperl.pod.9.html#LogOutput_r_out_basepath_">LogOutput ($r, $out, $basepath)</A>
+ <LI><A href="Embperl.pod.10.html#ProxyInput_r_in_mtime_sr">ProxyInput ($r, $in, $mtime, $src, $dest)</A>
+ <LI><A href="Embperl.pod.10.html#LogOutput_r_out_basepath_">LogOutput ($r, $out, $basepath)</A>
</UL>
- <LI><A href="Embperl.pod.10.html#Inside_Embperl_How_the_embedde">Inside Embperl - How the embedded Perl code is actually processed</A>
+ <LI><A href="Embperl.pod.11.html#Inside_Embperl_How_the_embedde">Inside Embperl - How the embedded Perl code is actually processed</A>
<UL>
- <LI><A href="Embperl.pod.10.html#1_Remove_the_HTML_tags_Now_it_">1. Remove the HTML tags. Now it looks like</A>
- <LI><A href="Embperl.pod.10.html#2_Translate_HTML_escapes_to_ASC">2. Translate HTML escapes to ASCII characters</A>
- <LI><A href="Embperl.pod.10.html#3_Remove_all_carriage_returns">3. Remove all carriage returns</A>
- <LI><A href="Embperl.pod.10.html#4_Eval_perl_code_into_a_subrout">4. Eval perl code into a subroutine</A>
- <LI><A href="Embperl.pod.10.html#5_Call_the_subroutine">5. Call the subroutine</A>
- <LI><A href="Embperl.pod.10.html#6_Escape_special_characters_in_">6. Escape special characters in the return value</A>
- <LI><A href="Embperl.pod.10.html#7_Send_the_return_value_as_outp">7. Send the return value as output to the destination</A>
+ <LI><A href="Embperl.pod.11.html#1_Remove_the_HTML_tags_Now_it_">1. Remove the HTML tags. Now it looks like</A>
+ <LI><A href="Embperl.pod.11.html#2_Translate_HTML_escapes_to_ASC">2. Translate HTML escapes to ASCII characters</A>
+ <LI><A href="Embperl.pod.11.html#3_Remove_all_carriage_returns">3. Remove all carriage returns</A>
+ <LI><A href="Embperl.pod.11.html#4_Eval_perl_code_into_a_subrout">4. Eval perl code into a subroutine</A>
+ <LI><A href="Embperl.pod.11.html#5_Call_the_subroutine">5. Call the subroutine</A>
+ <LI><A href="Embperl.pod.11.html#6_Escape_special_characters_in_">6. Escape special characters in the return value</A>
+ <LI><A href="Embperl.pod.11.html#7_Send_the_return_value_as_outp">7. Send the return value as output to the destination</A>
</UL>
- <LI><A href="Embperl.pod.11.html#Performance">Performance</A>
- <LI><A href="Embperl.pod.12.html#Bugs">Bugs</A>
- <LI><A href="Embperl.pod.13.html#Compatibility">Compatibility</A>
+ <LI><A href="Embperl.pod.12.html#Performance">Performance</A>
+ <LI><A href="Embperl.pod.13.html#Bugs">Bugs</A>
+ <LI><A href="Embperl.pod.14.html#Compatibility">Compatibility</A>
<UL>
- <LI><A href="Embperl.pod.13.html#on_Linux_2_x_with">on Linux 2.x with</A>
- <LI><A href="Embperl.pod.13.html#on_Windows_NT_4_0_with">on Windows NT 4.0 with</A>
- <LI><A href="Embperl.pod.13.html#on_Windows_95_98_with">on Windows 95/98 with</A>
+ <LI><A href="Embperl.pod.14.html#on_Linux_2_x_with">on Linux 2.x with</A>
+ <LI><A href="Embperl.pod.14.html#on_Windows_NT_4_0_with">on Windows NT 4.0 with</A>
+ <LI><A href="Embperl.pod.14.html#on_Windows_95_98_with">on Windows 95/98 with</A>
</UL>
- <LI><A href="Embperl.pod.14.html#Support">Support</A>
+ <LI><A href="Embperl.pod.15.html#Support">Support</A>
<UL>
- <LI><A href="Embperl.pod.14.html#Feedback_and_Bug_Reports">Feedback and Bug Reports</A>
- <LI><A href="Embperl.pod.14.html#Commerical_Support">Commerical Support</A>
+ <LI><A href="Embperl.pod.15.html#Feedback_and_Bug_Reports">Feedback and Bug Reports</A>
+ <LI><A href="Embperl.pod.15.html#Commerical_Support">Commerical Support</A>
</UL>
- <LI><A href="Embperl.pod.15.html#References">References</A>
+ <LI><A href="Embperl.pod.16.html#References">References</A>
<UL>
- <LI><A href="Embperl.pod.15.html#Information">Information</A>
- <LI><A href="Embperl.pod.15.html#Download">Download</A>
- <LI><A href="Embperl.pod.15.html#CVS">CVS</A>
+ <LI><A href="Embperl.pod.16.html#Information">Information</A>
+ <LI><A href="Embperl.pod.16.html#Download">Download</A>
+ <LI><A href="Embperl.pod.16.html#CVS">CVS</A>
</UL>
- <LI><A href="Embperl.pod.16.html#Author">Author</A>
+ <LI><A href="Embperl.pod.17.html#Author">Author</A>
</UL>
<!-- INDEX END -->
-<hr><p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.1.html">NEXT (Operating-Modes)</a>] <br>
+<hr><p>[<a href="index.html">HOME</a>] [<a href="Embperl.pod.cont.html">CONTENT</a>] [<a href="Embperl.pod.1.html">NEXT (DESCRIPTION)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
HTML::Embperl - Copyright (c) 1997-1999 Gerald Richter / ECOS
</font></p>
1.9 +1 -1 modperl-site/embperl/Faq.pod.2.html
Index: Faq.pod.2.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Faq.pod.2.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- Faq.pod.2.html 1999/10/04 16:02:14 1.8
+++ Faq.pod.2.html 2000/02/20 20:29:32 1.9
@@ -138,7 +138,7 @@
<P>
For a list of all possible metacommands, see the section on
-<A HREF="Embperl.pod.3.html#_Cmd_Arg_Meta_Commands_">Meta-Commands</A> in the Embperl documentation.
+<A HREF="Embperl.pod.4.html#_Cmd_Arg_Meta_Commands_">Meta-Commands</A> in the Embperl documentation.
<P>
<PRE> [$ while $st -> fetch $]
1.13 +2 -2 modperl-site/embperl/Faq.pod.3.html
Index: Faq.pod.3.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Faq.pod.3.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- Faq.pod.3.html 1999/10/13 05:48:40 1.12
+++ Faq.pod.3.html 2000/02/20 20:29:32 1.13
@@ -222,7 +222,7 @@
</PRE>
<P>
For a list of all possible metacommands, see the section on
-<A HREF="Embperl.pod.3.html#_Cmd_Arg_Meta_Commands_">Meta-Commands</A> in the Embperl documentation.
+<A HREF="Embperl.pod.4.html#_Cmd_Arg_Meta_Commands_">Meta-Commands</A> in the Embperl documentation.
<P>
<HR>
@@ -234,7 +234,7 @@
etc.
<P>
-For more on security, please see <A HREF="Embperl.pod.7.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> in the Embperl documentation.
+For more on security, please see <A HREF="Embperl.pod.8.html#_Safe_Namespaces_and_opcode_res">(Safe-)Namespaces and opcode restrictions</A> in the Embperl documentation.
<P>
<HR>
1.10 +2 -2 modperl-site/embperl/Faq.pod.4.html
Index: Faq.pod.4.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Faq.pod.4.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- Faq.pod.4.html 1999/10/04 16:02:16 1.9
+++ Faq.pod.4.html 2000/02/20 20:29:32 1.10
@@ -59,7 +59,7 @@
<P>
To see the exact steps taken by Embperl to process a Perl-laden document,
-please see the section <A HREF="Embperl.pod.10.html#Inside_Embperl_How_the_embedde">Inside Embperl</A> in the Embperl documentation.
+please see the section <A HREF="Embperl.pod.11.html#Inside_Embperl_How_the_embedde">Inside Embperl</A> in the Embperl documentation.
<P>
<HR>
@@ -188,7 +188,7 @@
<P>
To see the exact steps taken by Embperl to process a Perl-laden document,
-please see <A HREF="Embperl.pod.10.html#Inside_Embperl_How_the_embedde">Inside Embperl</A> in the Embperl documentation.
+please see <A HREF="Embperl.pod.11.html#Inside_Embperl_How_the_embedde">Inside Embperl</A> in the Embperl documentation.
<P>
<HR>
1.9 +1 -1 modperl-site/embperl/Faq.pod.5.html
Index: Faq.pod.5.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Faq.pod.5.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- Faq.pod.5.html 1999/10/04 16:02:16 1.8
+++ Faq.pod.5.html 2000/02/20 20:29:32 1.9
@@ -45,7 +45,7 @@
<P>
For more on using HTML links to the Embperl error log, see
-<A HREF="Embperl.pod.2.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> in the Embperldocs.
+<A HREF="Embperl.pod.3.html#EMBPERL_DEBUG">EMBPERL_DEBUG</A> in the Embperldocs.
<P>
<HR>
1.9 +1 -1 modperl-site/embperl/Faq.pod.8.html
Index: Faq.pod.8.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/Faq.pod.8.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- Faq.pod.8.html 1999/10/04 16:02:19 1.8
+++ Faq.pod.8.html 2000/02/20 20:29:32 1.9
@@ -31,7 +31,7 @@
HREF="mailto:info@ecos.de.">info@ecos.de.</A>
<P>
-Please also see the section <A HREF="Embperl.pod.14.html#Support">Support</A> in the Embperl documentation.
+Please also see the section <A HREF="Embperl.pod.15.html#Support">Support</A> in the Embperl documentation.
<p>[<a href="index.html">HOME</a>] [<a href="Faq.pod.cont.html">CONTENT</a>] [<a href="Faq.pod.7.html">PREV (Optimizing & Fine-Tuning)</a>] [<a href="Faq.pod.9.html">NEXT (AUTHOR)</a>] <br>
<font color="#808080">___________________________________________________________________________________<br>
1.76 +7 -3 modperl-site/embperl/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/modperl-site/embperl/index.html,v
retrieving revision 1.75
retrieving revision 1.76
diff -u -r1.75 -r1.76
--- index.html 2000/02/11 22:34:16 1.75
+++ index.html 2000/02/20 20:29:32 1.76
@@ -44,10 +44,10 @@
<td bgcolor="#bFcDdA"><big> <a href="Changes.pod.cont.html">Changes</a> </big></td>
</tr>
<tr>
- <td bgcolor="#AFBDCA"><big> <a href="Embperl.pod.14.html">Support</a> </big></td>
+ <td bgcolor="#AFBDCA"><big> <a href="Embperl.pod.15.html">Support</a> </big></td>
</tr>
<tr>
- <td bgcolor="#bFcDdA"><big> <a href="Embperl.pod.15.html">See Also/Download</a> </big></td>
+ <td bgcolor="#bFcDdA"><big> <a href="Embperl.pod.16.html">See Also/Download</a> </big></td>
</tr>
<tr>
<td bgcolor="#AFBDCA"><big> <a href="Sites.pod.1.html">Sites using Embperl</a> </big></td>
@@ -67,6 +67,9 @@
<tr>
<td bgcolor="#bFcDdA"><big> <a href="mirror.html">WorldWide Mirrors</a> </big></td>
</tr>
+ <tr>
+ <td bgcolor="#bFcDdA"><big> <a href="http://perl.apache.org/jobs.html">Jobs</a> </big></td>
+ </tr>
<tr>
<td bgcolor="#AFBDCA"><big> </big></td>
</tr>
@@ -138,7 +141,8 @@
<tr bgcolor="#bFcDdA">
<td vAlign="top"><img height="13" src="bullet.gif" width="13"></td>
<td vAlign="top">11. Feb 2000</td>
- <td><font face="Helvetica,Arial" size="2">Embperl 1.3b2 released</font></td>
+ <td><font face="Helvetica,Arial" size="2">Embperl 1.3b2 released. This release contains
+ the new <a href="EmbperlObject.pod.cont.html"><b>EmbperlObject</b></a> which really simplify building a website out of small reusable pieces</font></td>
</tr>
<tr bgcolor="#AFBDCA">
<td vAlign="top"><img height="13" src="bullet.gif" width="13"></td>
@@ -246,7 +250,7 @@
<blockquote>
<p><font color="#808080" size=1><hr>
HTML::Embperl - Copyright (c) 1997-2000 Gerald Richter / ECOS <richter@dev.ecos.de>
- Last Update $Id: index.html,v 1.75 2000/02/11 22:34:16 richter Exp $</font></p>
+ Last Update $Id: index.html,v 1.76 2000/02/20 20:29:32 richter Exp $</font></p>
</blockquote>
</td></tr><!--msnavigation--></table></body>
</html>