Home : Documentation : 1.3.6 documentation : HTML::Embperl
Google Web perl.apache.org

 
Home
 
Features
 
Introduction
 
Documentation
 
README
 
README.v2
 
Configuration
 
Embperl
 
Embperl::Object
 
Embperl::Form::Validate
 
Embperl::Syntax
 
Embperl::Recipe
 
Embperl::Mail
 
1.3.6 documentation
 
HTML::Embperl
 
HTML::EmbperlObject
 
HTML::Embperl::Mail
 
HTML::Embperl::Session
 
Tips & Tricks
 
FAQ
 
DBIx::Recordset
 
Installation
 
Download
 
Support
 
Changes
 
Wiki
 
More infos
 
Add info about Embperl
 
Login

    Stable 2.4.0
    Beta 2.5.0_3
Support the development of Embperl! More...
Runtime configuration
[ << Prev: Operating-Modes ] [ Content ] [ Next: SYNTAX >> ]

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:

SetEnv <var> <value>

If you are using Apache and mod_perl you can use

PerlSetEnv <var> <value>

The advantage of PerlSetEnv over SetEnv is that it can be used on a per directory/virtual host basis.



EMBPERL_FILESMATCHtop

If specified, only files which match the given perl regular expression 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) residing in the same directory. EMBPERL_FILESMATCH works only under mod_perl.

 Example: 
 # Only files which end with .htm will processed by Embperl
 PerlSetEnv EMBPERL_FILESMATCH \.htm$


EMBPERL_ALLOW (only 1.2b10 and above)top

If specified, only files which match the given perl regular expression will be processed by Embperl. All other files will return FORBIDDEN. This is especially useful in a CGI environment by making the server more secure.



EMBPERL_PATH (1.3b6 and above)top

Can contain a semicolon (also colon under Unix) separated file search path. When a file is processed and the filename isn't an absolute path or does not start with ./ (or .\ under windows), Embperl searches all the specified directories for that file. Directories must end with a slash (/), otherwise the entry is treated as a fileprefix. A special handling is done if the filename starts with any number of ../ i.e. refers to an upper directory. Then Embperl strips the same number of entries at the start of the searchpath as the filename contains ../.



EMBPERL_COMPARTMENTtop

Gives the name of the compartment from which to take the opcode mask. (See the chapter about (Safe-)Namespaces and opcode restrictions for more details.)



EMBPERL_ESCMODEtop

Specifies the initial value for $escmode (see below).



EMBPERL_LOGtop

Gives the location of the log file. This will contain information about what Embperl is doing. The amount of information depends on the debug settings (see EMBPERL_DEBUG below). The log output is intended to show what your embedded Perl code is doing and to help debug it. The default is /tmp/embperl.log.

NOTE: When running under mod_perl you need to use PerlSetEnv for setting the logfile path, and mod_perl >= 1.07_03 if you load Embperl at server startup (with PerlScript or PerlModule).



EMBPERL_PACKAGEtop

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 do not conflict with those of another file. (Any package's variables will still be accessible with explicit package names.)



EMBPERL_VIRTLOGtop

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 EMBPERL_DEBUG and dbgLogLink for an Example on how to set it up in your srm.conf.



EMBPERL_OPTIONStop

This bitmask specifies some options for the execution of Embperl. To specify multiple options, simply add the values together.

 

optDisableVarCleanup = 1

 

Disables the automatic cleanup of variables at the end of each request.

 

optDisableEmbperlErrorPage = 2

 

Tells Embperl not to send its own errorpage in case of failure, but instead show 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.

 

optReturnError = 262144

 

With this option set, Embperl sends no output in case of an error. It returns the error back to Apache or the calling program. When running under mod_perl this gives you the chance to use the Apache ErrorDocument directive to show a custom error-document. Inside the ErrorDocument you can retrieve the error messages with

  $errors = $req_rec -> prev -> pnotes('EMBPERL_ERRORS') ;

where $errors is a array reference. (1.3b5+)

 

optShowBacktrace = 0x8000000

 

When set every error message not only show the sourcefiles, but all files from which this file was called by Execute.

 

optSafeNamespace = 4

 

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 (Safe-)Namespaces and opcode restrictions below for more details.)

 

optOpcodeMask = 8

 

Tells Embperl to apply an operator mask. This gives you the chance to disallow special (unsafe) opcodes. (See the Chapter about (Safe-)Namespaces and opcode restrictions below for more details.)

 

optRawInput = 16

 

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.

If you are using a WYSIWYG editor which inserts unwanted HTML tags in your Perl expressions and escapes special characters 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.

 

optEarlyHttpHeader = 64

 

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.

 

optDisableChdir = 128

 

By default, Embperl changes the current directory to the one where the script resides, thus giving 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.

 

optDisableFormData = 256

 

This option disables the setup of %fdat and @Z<>ffld. Embperl will not do anything with the posted form data. Set this when using Execute from your perl script and you have already read the Form Data (via eg. CGI.pm).

 

optDisableHtmlScan = 512

 

When set, this option disables the scanning of all html-tags. Embperl will only look for [+/-/!/$ ... $/!/-/+]. This will disable dynamic tables, processing of the input data and so on.

 

optDisableInputScan = 1024

 

Disables processing of all input-related tags. (<INPUT><TEXTAREA><OPTION>)

 

optDisableTableScan = 2048

 

Disables processing of all table-related tags. (<TABLE><TH><TR><TD><MENU><OL><UL>)

 

optDisableSelectScan = 8388608 (0x800000) (only 1.3b7 and above)

 

Disables processing of the SELECT tag. (<SELECT>)

 

optDisableMetaScan = 4096

 

Disables processing of all meta tags. (<META HTTP-EQUIV>)

 

optAllFormData = 8192

 

This option will cause Embperl to insert all formfields in %fdat and @Z<>ffld, even if they are empty. Empty formfields will be inserted with an empty string. Without this option, empty formfields will be absent from %fdat and @Z<>ffld.

 

optRedirectStdout = 16384

 

Redirects STDOUT to the Embperl output stream before every request and resets it afterwards. If set, you can use a normal Perl print inside any Perl block to output data. Without this option you can only use output data by using the [+ ... +] block, or printing to the filehandle OUT.

 

optUndefToEmptyValue = 32768

 

Normally, if there is no value in %fdat 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 %fdat for the field.

 

optNoHiddenEmptyValue = 65536 (only 1.2b2 and above)

 

Normally, if there is a value defined in %fdat for a specific input field, Embperl will output a hidden input element for it when you use hidden. When this option is set, Embperl will not output a hidden input element for this field when the value is a blank string.

 

optAllowZeroFilesize = 131072 (only 1.2b2 and above)

 

Normaly Embperl reports NOT_FOUND (404) if a file of length zero is requested. With this option set, Embperl will return an empty document.

 

optKeepSrcInMemory = 524288 (only 1.2b5 and above)

 

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)

 

optKeepSpaces = 1048576 (only 1.2b5 and above) = 0x100000,

 

Disable the removal of spaces and empty lines from the output. This is useful for sources other than HTML.

 

optOpenLogEarly = 2097152 (only 1.2b5 and above)

 

This option causes 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)

Disable the warnings about unclosed if, while, table etc. at the end of the file.



EMBPERL_DEBUGtop

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:

 

dbgStd = 1

 

Show minimum information.

 

dbgMem = 2

 

Show memory and scalar value allocation.

 

dbgEval = 4

 

Show arguments to and results of evals.

 

dbgCmd = 8

 

Show metacommands and HTML tags which are processed.

 

dbgEnv = 16,

 

List every request's environment variables.

 

dbgForm = 32

 

List posted form data.

 

dbgTab = 64

 

Show processing of dynamic tables.

 

dbgInput = 128

 

Show processing of HTML input tags.

 

dbgFlushOutput = 256

 

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.

 

dbgFlushLog = 512

 

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.

 

dbgAllCmds = 1024

 

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

 

dbgSource = 2048

 

Logs the next piece of the HTML source to be processed. (NOTE: This generates a lot of output!)

 

dbgFunc = 4096

 

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.

 

dbgLogLink = 8192

 

Inserts a link at the top of each page which can be used to view the log for the current HTML file. See also EMBPERL_VIRTLOG.

Example:

    SetEnv EMBPERL_DEBUG 10477
    SetEnv EMBPERL_VIRTLOG /embperl/log

    <Location /embperl/log>
    SetHandler perl-script
    PerlHandler HTML::Embperl
    Options ExecCGI
    </Location>
 

dbgDefEval = 16384

 

Shows every time new Perl code is compiled.

 

dbgHeadersIn = 262144

 

Log all HTTP headers which are sent from the browser.

 

dbgShowCleanup = 524288

 

Show every variable which is undef'd at the end of the request. For scalar variables, the value before undef'ing is logged.

 

dbgProfile = 1048576 (only 1.2b4 and above)

 

When set every source line in the log file will also display the time until request was started. (dbgSource must also be set)

 

dbgSession = 2097152 (only 1.2b4 and above)

 

Enables logging of session transactions.

 

dbgImport = 4194304 (only 1.2b5 and above)

 

Show how subroutines are imported in other namespaces.

A good value to start is 2285 or 10477 if you want to view the logfile with your browser. (Don't forget to set EMBPERL_VIRTLOG.) If Embperl crashes, add 512 so the logfile is flushed after every line is written and you can see where Embperl is when it crashes.



EMBPERL_INPUT_FUNCtop

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 Execute). 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:

 InputFunc ($r, $in, $cacheargs, additional parameters...) ;
 

$r

 

Apache Request Record (see perldoc Apache for details)

 

$in

 

a reference to a scalar, to which the input should be returned.

 Example:

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

$cacheargs

 

a reference to a scalar, to which the modification time should be returned. Alternatively (1.2.1 and up), you can return a reference to a hash with the elements mtime and inputfile which are used to correcly cache the precompiled Perlcode.

 Example:

 $$cacheargs = -M "filename" ;

 or

 $$cacheargs = { mtime => -M "filename", inputfile => "filename" }  ;

You can give additional parameters (which must be comma-separated) to EMBPERL_INPUT_FUNC which will then pass them as a string.

  Example:

  PerlSetEnv EMBPERL_INPUT_FUNC "InputFunc, foo, bar"

  will call

  InputFunc ($r, $in, $mtime, 'foo', 'bar') ;

  to get the input.

EXAMPLE for an input function which does just the same as Embperl

 sub Input

    {
    my ($r, $in, $mtime) = @_ ;

    open F, $r -> filename or return NOT_FOUND ;
    local $\ = undef ;
    $$in = <F> ;
    close F ;

    $$mtime = -M $r -> filename ;
    
    return 0 ;
    }

See also ProxyInput below, for an input function which comes with Embperl.

NOTE: There are also two modules (HTML::EmbperlChain and Apache::EmbperlFilter) which allow you to chain Embperl and other modules together.



EMBPERL_OUTPUT_FUNCtop

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 Execute). 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:

 OutputFunc ($r, $out, additional parameters...) ;
 

$r

 

Apache Request Record (see perldoc Apache for details)

 

$out

 

a reference to a scalar, which contains the output from Embperl

You can give additional parameters (which must be comma-separated) to EMBPERL_OUTPUT_FUNC, which will then pass them as a string.

  Example:

  PerlSetEnv EMBPERL_OUTPUT_FUNC "OutputFunc, foo, bar"

  will call

  OutputFunc ($r, $out, 'foo', 'bar') ;

  for output.

EXAMPLE for an ouput function which does just the same as Embperl

 sub Output

    {
    my ($r, $out) = @_ ;

    $r -> send_http_header ;

    $r -> print ($$out) ;

    return 0 ;
    }

See also LogOutput below, for an output function which comes with Embperl.

NOTE: There are also two modules (HTML::EmbperlChain and Apache::EmbperlFilter) which allow you to chain Embperl and other modules together.



EMBPERL_MAILHOSTtop

Specifies which host the MailFormTo function uses as SMTP server. Default is localhost.



EMBPERL_MAILHELOtop

(only 1.3b4 or above) Specifies which host/domain the MailFormTo function uses in the HELO/EHLO command. A reasonable default is normaly choosen by Net::SMTP, but depending on your installation it may neccessary to set it manualy.



EMBPERL_MAILFROMtop

(only 1.2.1 or above) Specifies which the email address that is used as sender by MailFormTo. Default is www-server@server_name.



EMBPERL_MAILDEBUGtop

(only 1.2.1 or above) Debugsetting for Net::SMTP. Default is 0.



EMBPERL_MAIL_ERRORS_TOtop

If set all errors will be send to the email adress given.



EMBPERL_COOKIE_NAMEtop

(only 1.2b4 or above) Set the name that Embperl uses when it sends the cookie with the session id. Default is EMBPERL_UID.



EMBPERL_COOKIE_DOMAINtop

(only 1.2b4 or above) Set the domain that Embperl uses for the cookie with the session id. Default is none.



EMBPERL_COOKIE_PATHtop

(only 1.2b4 or above) Set the path that Embperl uses for the cookie with the session id. Default is none.



EMBPERL_COOKIE_EXPIREStop

(only 1.2b4 or above) Set the expiration date that Embperl uses for the cookie with the session id. You can specify the full date or relativ values (1.3b5 or higher). Examples: +30s +10m +1h -1d +3M +10y Default is none.



EMBPERL_SESSION_CLASSEStop

Space separated list of object store and lock manager (and optionally the serialization and id generating class) for Apache::Session (see Session handling)



EMBPERL_SESSION_ARGStop

List of arguments for Apache::Session classes (see Session handling) Arguments that contains spaces can be quoted. Example:

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


EMBPERL_SESSION_HANDLER_CLASS (1.3b3 and higher)top

Set the class that performs the Embperl session handling. Default until 1.3.3 was HTML::Embperl::Session, starting with 1.3.4 it is Apache::SessionX. To get the old session behaviour set it to HTML::Embperl::Session. You can overwrite HTML::Embperl::Session and specify the name of your class within this variable. This gives you the possibility to implement your own session handling.


[ << Prev: Operating-Modes ] [ Content ] [ Next: SYNTAX >> ]

© 1997-2012 Gerald Richter / ecos gmbh