=head1 NAME Embperl::Config - Embperl configuration and calling =head1 Operating-Modes Embperl can operate in one of four modes: =over =item mod_perl The mostly used way is to use Embperl together with mod_perl and Apache. This gives the best performance and the most possibilities. =item CGI/FastCGI When you want to run Embperl on a machine that doesn't have mod_perl, you can run Embperl also as normal CGI script. Due to the overhead of CGI, this mode is much slower. To get a better performance you should consider using Embperl together with FastCGI. (http://www.fastcgi.com). =item Offline You can use Embperl also on the command line. This is useful for generating static content out of dynamic pages and can sometime be helpful for testing. =item Call it from other Perl programs If you have your own application and want to use Embperl's capbilities you can do so by calling Embperl::Execute. This allows you to build your own application logic and use Embperl possibilities for rendering content. =back =head2 mod_perl To use Embperl under mod_perl you must have installed Apache and mod_perl on your system. Then you add some directives to your F to load Embperl and add C as the C. The following directives will cause all file with extetion F to be handled by Embperl: PerlModule Embperl AddType text/html .epl SetHandler perl-script PerlHandler Embperl Options ExecCGI Another possibility is to have all files under a special location processed by Embperl: PerlModule Embperl Alias /embperl /path/to/embperl/eg SetHandler perl-script PerlHandler Embperl Options ExecCGI In this setup you should make sure that non Embperl files like images doesn't served from this directory. For B you need addtionaly to load the dynamic object library of Embperl. This is necessary so Embperl is loaded early enough to register the configuration directives with Apache. After installing, search underneath your Perl site directory for the library. On Unix it is mostly called F on Windows it is called C. Now add the following line to your httpd.conf B any of the Embperl configuration directives, but B F is loaded: LoadModule embperl_module /path/to/perl/site/lib/Embperl/Embperl.so To use I you use the C as C: Embperl_AppName unique-name Embperl_Object_Base base.htm Embperl_UriMatch "\.htm.?|\.epl$" SetHandler perl-script PerlHandler Embperl::Object Options ExecCGI Addtionaly you can setup other parameters for I. If you do so inside a container (like C<, , >) you need to set C to a unique-name (the actual value doesn't matter). The C makes sure that only files of the requested type are served by I, while all others are served by Apache as usual. For more information see: L<"perldoc Embperl::Object"|"EmbperlObject.pod">. Embperl accepts a lot of configuration directives to customize it's behaviour. See the next section for a description. B If mod_perl is statically linked into Apache you can not use B in your httpd.conf =head3 Preloading pages To optimize memory usage you can preload your pages during the initialization. If you do so they will get loaded into the parent process and the memory will be shared by all child processes. To let Embperl preload your files, you have to supply all the filename into the key B of the hash B<%initparam>, B you load Embperl. Example: BEGIN { $Embperl::initparam{preloadfiles} = [ '/path/to/foo.epl', '/path/to/bar.epl', { inputfile => "/path/to/other.epl", input_escmode => 7 }, ] ; } use Embperl ; As you see for the third file, it is also possible to give a hashref and supply the same parameter like L accpets (see below). B Preloading is not supported under Apache 1.3, when mod_perl is loaded as DSO. To use preloading under Apache 1.3 you need to compile mod_perl statically into Apache. =head2 CGI/FastCGI To use this mode you must copy B to your cgi-bin directory. You can invoke it with the URL http://www.domain.xyz/cgi-bin/embpcgi.pl/url/of/your/document. 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. If you are running the Apache httpd, you can also define B as a handler for a specific file extension or directory. Example of Apache C: Action text/html /cgi-bin/embperl/embpcgi.pl B: Via CGI Scripts it maybe possible to bypass some of the Apache setup. To avoid this use L to restrict access to the files, which should be processed by Embperl. For I you have to use F instead of F. You can also run Embperl with B, in this case use embpfastcgi.pl as cgi script. You must have FCGI.pm installed. =head2 Offline Run Embperl from the comannd line use F on unix and F on windows: B B =over 4 =item B The full pathname of the source file which should be processed by Embperl. =item B 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. should be URL-encoded. The default is no query string. =back Options: =over =item -o outputfile Optional. Gives the filename to which the output is written. The default is stdout. =item -l logfile Optional. Gives the filename of the logfile. The default is F on unix and F<\embperl.log> on windows. =item -d debugflags Optional. Specifies the level of debugging (what is written to the log file). The default is nothing. See L<"EMBPERL_DEBUG"> for exact values. =item -t options See L<"EMBPERL_OPTIONS"> for option values. =item -s syntax Defines the syntax of the source. See See L<"EMBPERL_SYNTAX"> =item -p param Gives a value which is passed in the @param array to the executed page. Can be given multiple times. =item -f fdat value Gives a name/value pair which is passed in the %fdat hash to the executed page. Can be given multiple times. =back =head2 By calling Embperl::Execute (\%param) C 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 to nest multiple Embperl pages (for example to store a common header or footer in a different file). (See B for more detailed examples) When you want to use I call C, when you want I, call C. There are two forms you can use for calling Execute. A short form which only takes a filename and optional additional parameters or a long form which takes a hash reference as its argument. Execute($filename, $p1, $p2, $pn) ; This will cause Embperl to interpret the file with the name C<$filename> and, if specified, pass any additional parameters in the array C<@param> (just like C<@_> in a Perl subroutine). The above example could also be written in the long form: Execute ({inputfile => $filename, param => [$p1, $p2, $pn]}) ; The possible items for hash of the long form are are descriped in the configuration section and parameter section. =head3 EXAMPLES for Execute: # Get source from /path/to/your.html and # write output to /path/to/output' Embperl::Execute ({ inputfile => '/path/to/your.html', outputfile => '/path/to/output'}) ; # Get source from scalar and write output to stdout # Don't forget to modify mtime if $src changes $src = 'Page [+ $no +]' ; Embperl::Execute ({ inputfile => 'some name', input => \$src, mtime => 1 }) ; # Get source from scalar and write output to another scalar my $src = 'Page [+ $no +]' ; my $out ; Embperl::Execute ({ inputfile => 'another name', input => \$src, mtime => 1, output => \$out }) ; print $out ; # Include a common header in an Embperl page, # which is stored in /path/to/head.html [- Execute ('/path/to/head.html') -] =head2 Debugging Starting with 2.0b2 Embperl files can debugged via the interactive debugger. The debugger shows the Embperl page source along with the correct linenumbers. You can do anything you can do inside a normal Perl program via the debugger, e.g. show variables, modify variables, single step, set breakpoints etc. You can use the Perl interacive command line debugger via perl -d embpexec.pl file.epl or if you prefer a graphical debugger, try ddd (http://www.gnu.org/software/ddd/) it's a great tool, also for debugging any other perl script: ddd --debugger 'perl -d embpexec.pl file.epl' NOTE: embpexec.pl could be found in the Embperl source directory If you want to debug your pages, while running under mod_perl, Apache::DB is the right thing. Apache::DB is available from CPAN. =head1 Configuration Configuration can be setup in different ways, depending how you run Embperl. When you run under mod_perl, Embperl add a set of new configuration directives to the Apache configuration, so you can set them in your F. When you run Embperl as CGI it takes the configuration from environment variables. For compatibility reason that can also be turned on under mod_perl, by adding C in your F. When you call Embperl from another Perl program, by calling the C function, you can pass your configuration along with other parameters as a hash reference. If you pass C als parameter Embperl will also scan the environment for configuration information. Last but not least you can pass configuration information as options when you run Embperl via embpexec.pl from the command line. Some of the configuration options are also setable inside the page via the Empberl objects and you can read the current configuration from these objects. You can not only pass configuration in different ways, there are also three different contexts: I, I and I. A application describes a set of pages/files that belongs together and form the application. Application level configuration are the same for all files that belongs to an application. These configuration information need to be known before any request processing takes place, so they can't be modified during a request. Every application has it's own name. You can refer the configuration of an application, by simply setting the name of the application to use. Request level configuration information applies to one request, some of them must be known before the request starts, some of them can still be modified during the request. Configuration for components can be setup before the request, but can also be passed as argument when you call the component via C. =head2 Embperl_Useenv =over =item Env: EMBPERL_USEENV =item Method: $application -> config -> use_env I<[read only]> =item Default: off unless runing as CGI script =item Since: 2.0b6 =back Tells Embperl to scan the enviromemt for configuration settings. =head2 use_redirect_env =over =item Method: $application -> config -> use_redirect_env I<[read only]> =item Default: off unless runing as CGI script =item Since: 2.0b6 =back Tells Embperl to scan the enviromemt for configuration settings which has the prefix C. This is normally the case when the request is not the main request, but a subrequest. =head2 Embperl_Appname =over =item Env: EMBPERL_APPNAME =item Method: $application -> config -> app_name I<[read only]> =item Since: 2.0b6 =back Specifies the name for an application. The name is basicly used to refer to this application elsewhere in httpd.conf without the need to setup the parameters for the apllication again. =head2 Embperl_App_Handler_Class =over =item Env: EMBPERL_APP_HANDLER_CLASS =item Method: $application -> config -> app_handler_class I<[read only]> =item Since: 2.0b6 =back Embperl will call the C method of the given class at the start of the request, but after all request parameters are setup. This give the class a chance to do any necessary computation and modify the request parameters, before the request is actualy executed. See L for an example. =head2 Embperl_Session_Handler_Class =over =item Env: EMBPERL_SESSION_HANDLER_CLASS =item Method: $application -> config -> session_handler_class I<[read only]> =item Default: Apache::SessionX =item Since: 1.3b3 =item See also: Session Handling =back Set the class that performs the Embperl session handling. This gives you the possibility to implement your own session handling. NOTE: Default until 1.3.3 was C, starting with 1.3.4 it is C. To get the old session behaviour set it to C. =head2 Embperl_Session_Args =over =item Env: EMBPERL_SESSION_ARGS =item Method: $application -> config -> session_args I<[read only]> =item Since: 1.3b3 =item See also: Session Handling =back List of arguments for Apache::Session classes Arguments that contains spaces can be quoted. Example: EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=www 'Password=secret word'" =head2 Embperl_Session_Classes =over =item Env: EMBPERL_SESSION_CLASSES =item Method: $application -> config -> session_classes I<[read only]> =item Since: 1.3b3 =item See also: Session Handling =back Space separated list of object store and lock manager (and optionally the serialization and id generating class) for Apache::Session (see L<"Session handling">) =head2 Embperl_Session_Config =over =item Env: EMBPERL_SESSION_CONFIG =item Method: $application -> config -> session_config I<[read only]> =item Default: given when running Makefile.PL of Apache::SessionX =item Since: 1.3.3 =item See also: Session Handling =back Selects a session configuration from the configurations you have defined when running I's C. NOTE: Use either C or C and C =head2 Embperl_Cookie_Name =over =item Env: EMBPERL_COOKIE_NAME =item Method: $application -> config -> cookie_name I<[read only]> =item Default: EMBPERL_UID =item Since: 1.2b4 =item See also: Session Handling =back Set the name that Embperl uses when it sends the cookie with the session id. =head2 Embperl_Cookie_Domain =over =item Env: EMBPERL_COOKIE_DOMAIN =item Method: $application -> config -> cookie_domain I<[read only]> =item Default: none =item Since: 1.2b4 =item See also: Session Handling =back Set the domain that Embperl uses for the cookie with the session id. =head2 Embperl_Cookie_Path =over =item Env: EMBPERL_COOKIE_PATH =item Method: $application -> config -> cookie_path I<[read only]> =item Default: none =item Since: 1.2b4 =item See also: Session Handling =back Set the path that Embperl uses for the cookie with the session id. =head2 Embperl_Cookie_Expires =over =item Env: EMBPERL_COOKIE_EXPIRES =item Method: $application -> config -> cookie_expires I<[read only]> =item Default: at the end of the session =item Since: 1.3b5 =item See also: Session Handling =back Set the expiration date that Embperl uses for the cookie with the session id. You can specify the full date or relativ values. The following forms are all valid times: +30s 30 seconds from now +10m ten minutes from now +1h one hour from now -1d yesterday (i.e. "ASAP!") now immediately +3M in three months +10y in ten years time Thu, 25-Apr-1999 00:40:33 GMT at the indicated time & date =head2 Embperl_Cookie_Secure =over =item Env: EMBPERL_COOKIE_SECURE =item Method: $application -> config -> cookie_secure I<[read only]> =item Default: at the end of the session =item Since: 2.0b9 =item See also: Session Handling =back Set the secure flag of cookie that Embperl uses for the session id. If set the cookie will only be transferred over a secured connection. =head2 Embperl_Log =over =item Env: EMBPERL_LOG =item Method: $application -> config -> log I<[read only]> =item Default: Unix: /tmp/embperl.log Windows: /embperl.log =back 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 L<"EMBPERL_DEBUG"> below). The log output is intended to show what your embedded Perl code is doing and to help debug it. =head2 Embperl_Debug =over =item Env: EMBPERL_DEBUG =item Method: $application -> config -> debug =back This is a bitmask which specifies what should be written to the log. To specify multiple debugflags, simply add the values together. You can give the value a decimal, octal (prefix 0) or hexadecimal (prefix 0x) value. You can also use the constants defined in I. The following values are defined: =over 4 =item dbgStd = 1 (0x1) Show minimum information. =item dbgMem = 2 (0x2) Show memory and scalar value allocation. =item dbgEval = 4 (0x4) Show arguments to and results of evals. =item dbgEnv = 16 (0x10) List every request's environment variables. =item dbgForm = 32 (0x20) List posted form data. =item dbgInput = 128 (0x80) Show processing of HTML input tags. =item dbgFlushOutput = 256 (0x100) 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. =item dbgFlushLog = 512 (0x200) 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. =item dbgLogLink = 8192 (0x2000) This feature is not yet implemented in Embperl 2.0! Inserts a link at the top of each page which can be used to view the log for the current HTML file. See also L<"EMBPERL_VIRTLOG">. Example: EMBPERL_DEBUG 10477 EMBPERL_VIRTLOG /embperl/log.htm SetHandler perl-script PerlHandler Embperl Options ExecCGI =item dbgDefEval = 16384 (0x4000) Shows every time new Perl code is compiled. =item dbgHeadersIn = 262144 (0x40000) Log all HTTP headers which are sent from and to the browser. =item dbgShowCleanup = 524288 (0x80000) Show every variable which is undef'd at the end of the request. For scalar variables, the value before undef'ing is logged. =item dbgSession = 2097152 (0x200000) Enables logging of session transactions. =item dbgImport = 4194304 (0x400000) Show how subroutines are imported in other namespaces. =item dbgOutput = 0x08000 Logs the process of converting the internal tree strcuture to plain text for output =item dbgDOM = 0x10000 Logs things related to processing the internal tree data structure of documents =item dbgRun = 0x20000 Logs things related to execution of a document =item dbgBuildToken = 0x800000 Logs things related to creating the token tables for source parsing =item dbgParse = 0x1000000 Logs the parseing of the source =item dbgObjectSearch = 0x2000000 Shows how Embperl::Objects seraches sourcefiles =item dbgCache = 0x4000000 Logs cache related things =item dbgCompile = 0x8000000 Gives information about compiling the parsed source to Perl code =item dbgXML = 0x10000000 Logs things related to XML processing =item dbgXSLT = 0x20000000 Logs things related to XSLT processing =item dbgCheckpoint = 0x40000000 Logs things related to checkpoints which are internaly used during execution. This information is only useful if you have a deep knowledge of Embperl internals. =back =head2 Embperl_Maildebug =over =item Env: EMBPERL_MAILDEBUG =item Method: $application -> config -> maildebug =item Since: 1.2.1 =back Debug value pass to Net::SMTP. =head2 Embperl_Mailhost =over =item Env: EMBPERL_MAILHOST =item Method: $application -> config -> mailhost =item Default: localhost =back Specifies which host the mail related functions of Embperl uses as SMTP server. =head2 Embperl_Mailhelo =over =item Env: EMBPERL_MAILHELO =item Method: $application -> config -> mailhelo =item Default: chosen by Net::SMTP =item Since: 1.3b4 =back Specifies which host/domain all mailrealted function uses in the HELO/EHLO command. A reasonable default is normally chosen by I, but depending on your installation it may necessary to set it manualy. =head2 Embperl_Mailfrom =over =item Env: EMBPERL_MAILFROM =item Method: $application -> config -> mailfrom =item Default: www-server@ =item Since: 1.2.1 =back Specifies the email address that is used as sender all mailrelted function. =head2 Embperl_Mail_Errors_To =over =item Env: EMBPERL_MAIL_ERRORS_TO =item Method: $application -> config -> mail_errors_to =back If set all errors will be send to the email address given. =head2 Embperl_Mail_Errors_Limit =over =item Env: EMBPERL_MAIL_ERRORS_LIMIT =item Method: $application -> config -> mail_errors_limit I<[read only]> =item Since: 2.0b6 =back Do not mail more then errors. Set to 0 for no limit. =head2 Embperl_Mail_Errors_Reset_Time =over =item Env: EMBPERL_MAIL_ERRORS_RESET_TIME =item Method: $application -> config -> mail_errors_reset_time I<[read only]> =item Since: 2.0b6 =back Reset error counter if for seconds no error has occured. =head2 Embperl_Mail_Errors_Resend_Time =over =item Env: EMBPERL_MAIL_ERRORS_RESEND_TIME =item Method: $application -> config -> mail_errors_resend_time I<[read only]> =item Since: 2.0b6 =back Mail errors of seconds regardless of the error counter. =head2 Embperl_Object_Base =over =item Env: EMBPERL_OBJECT_BASE =item Method: $application -> config -> object_base I<[read only]> =item Default: _base.epl =item Since: 1.3b1 =back Name of the base page that Embperl::Objects searches for. =head2 Embperl_Object_App =over =item Env: EMBPERL_OBJECT_APP =item Method: $application -> config -> object_app =item Since: 2.0b6 =back Filename of the application object that Embperl::Object searches for. The file should contain the Perl code for the application object. There must be no package name given (as the package is set by Embperl::Object) inside the file, but the @ISA should point to Embperl::App. If set this file is searched through the same search path as any content file. After a successfull load the init method is called with the Embperl request object as parameter. The init method can change the parameters inside the request object to influence the current request. =head2 Embperl_Object_Addpath =over =item Env: EMBPERL_OBJECT_ADDPATH =item Method: $application -> config -> object_addpath =item Since: 1.3b1 =back Additional directories where Embperl::Object searches for pages. This search through the searchpath is always performed if in a call to Execute no path for the file is given. In F or as evironment variable directories are separated by C<;> (on Unix C<:> works also). The parameter for C and the application object method expects/returns an array reference. This path is B appended to the searchpath. =head2 Embperl_Object_Reqpath =over =item Env: EMBPERL_OBJECT_REQPATH =item Method: $application -> config -> object_reqpath =item Since: 2.0b12 =back Additional directories where Embperl::Object searches for files for the inital request. If a file is requested, but cannot be found at the given location, the directories given in the this path are additionally searched for the file. This applies only to the initial filename given to Embperl::Object and B to files called via Execute. In F or as evironment variable directories are separated by C<;> (on Unix C<:> works also). The parameter for C and the application object method expects/returns an array reference. Example: if you say Embperl_Object_Reqpath /a:/b:/c and you request /x/index.epl it will try /x/index.epl /a/index.epl /b/index.epl /c/index.epl and take the first one that is found. =head2 Embperl_Object_Stopdir =over =item Env: EMBPERL_OBJECT_STOPDIR =item Method: $application -> config -> object_stopdir =item Since: 1.3b1 =back Directory where Embperl::Object stops searching for the base page. =head2 Embperl_Object_Fallback =over =item Env: EMBPERL_OBJECT_FALLBACK =item Method: $application -> config -> object_fallback =item Since: 1.3b1 =back If the requested file is not found by Embperl::Object, the file given by C is displayed instead. If C isn't set a staus 404, NOT_FOUND is returned as usual. If the fileame given in C doesn't contain a path, it is searched thru the same directories as C. =head2 Embperl_Object_Handler_Class =over =item Env: EMBPERL_OBJECT_HANDLER_CLASS =item Method: $application -> config -> object_handler_class =item Since: 1.3b1 =back If you specify this, the template base and the requested page inherit all methods from this class. This class must contain C in his @ISA array. =head2 Embperl_Useenv =over =item Env: EMBPERL_USEENV =item Method: $request -> config -> use_env I<[read only]> =item Default: off unless runing as CGI script =item Since: 2.0b6 =back Tells Embperl to scan the enviromemt for configuration settings. =head2 use_redirect_env =over =item Method: $request -> config -> use_redirect_env I<[read only]> =item Default: off unless runing as CGI script =item Since: 2.0b6 =back Tells Embperl to scan the enviromemt for configuration settings which has the prefix C. This is normally the case when the request is not the main request, but a subrequest. =head2 Embperl_Allow =over =item Env: EMBPERL_ALLOW =item Method: $request -> config -> allow I<[read only]> =item Default: no restrictions =item Since: 1.2b10 =back If specified, only files which match the given B 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. =head2 Embperl_Urimatch =over =item Env: EMBPERL_URIMATCH =item Method: $request -> config -> urimatch I<[read only]> =item Default: process all files =item Since: 2.0b6 =back If specified, only files which match the given B 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. Example: # Only files which end with .htm will processed by Embperl EMBPERL_URIMATCH \.htm$ =head2 Embperl_Multfieldsep =over =item Env: EMBPERL_MULTFIELDSEP =item Method: $request -> config -> mult_field_sep I<[read only]> =item Default: \t =item Since: 2.0b6 =back Specifies the character that is used to separate multiple form values with the same name. =head2 Embperl_Path =over =item Env: EMBPERL_PATH =item Method: $request -> config -> path I<[read only]> =item Since: 1.3b6 =back 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), I searches all the specified directories for that file. A special handling is done if the filename starts with any number of C<../> i.e. refers to an upper directory. Then I strips the same number of entries at the start of the searchpath as the filename contains C<../>. C and the method of the request object expects/returns a array ref. =head2 Embperl_Debug =over =item Env: EMBPERL_DEBUG =item Method: $request -> config -> debug =back See application configuration for an describtion of possible values =head2 Embperl_Options =over =item Env: EMBPERL_OPTIONS =item Method: $request -> config -> options =back This bitmask specifies some options for the execution of Embperl. To specify multiple options, simply add the values together. =over 4 =item optDisableVarCleanup = 1 Disables the automatic cleanup of variables at the end of each request. =item 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. =item 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 I 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 C<$errors> is a array reference. (1.3b5+) =item optShowBacktrace = 0x8000000 When set every error message not only show the sourcefiles, but all files from which this file was called by Execute. =back =head2 Embperl_Output_Mode =over =item Env: EMBPERL_OUTPUT_MODE =item Method: $request -> config -> output_mode =item Default: HTML =item Since: 2.0b9 =back Set the desired output format. 0 for HTML and 1 XML. If set to XML all tags that are generated by Embperl will contain a closing slash to conform to XML specs. e.g. B If you set output_mode to XML you should also change L to XML escaping. =head2 Embperl_Output_Esc_Charset =over =item Env: EMBPERL_OUTPUT_ESC_CHARSET =item Method: $request -> config -> output_esc_charset I<[read only]> =item Default: ocharsetLatin1 = 1 =item Since: 2.0.2 =back Set the charset which to assume when escaping. This can only be set before the request starts (e.g. httpd.conf or top of the page). Setting it inside the page has undefined results. =over =item ocharsetUtf8 = 0 UTF-8 or any non known charset. Characters with codes above 128 will not be escaped at all =item ocharsetLatin1 = 1 ISO-8859-1, the default. When a Perl string has it's utf-8 bit set, this mode will behave the same as mode 0, i.e. will not escape anything above 128. =item ocharsetLatin2 = 2 ISO-8859-2. When a Perl string has it's utf-8 bit set, this mode will behave the same as mode 0, i.e. will not escape anything above 128. =back =head2 Embperl_Session_Mode =over =item Env: EMBPERL_SESSION_MODE =item Method: $request -> config -> session_mode I<[read only]> =item Default: smodeUDatCookie = 1 =item Since: 2.0b6 =back Specifies how the id for the session data is passed between requests. Possible values are: =over =item smodeNone = 0 No session id will be passed =item smodeUDatCookie = 1 The session id for the user session will be passed via cookie =item smodeUDatParam = 2 The session id for the user session will append as parameter to any URL and inserted as a hidden field in any form. =item smodeUDatUrl = 4 The session id for the user session will passed as a part of the URL. NOT YET IMPLEMENTED!! =item smodeSDatParam = 0x20 The session id for the state session will append as parameter to any URL and inserted as a hidden field in any form. =back You may add the UDat and SDat values together to get both sorts of sessions, for example the value 0x21 will pass the id for the user session inside a cookie and the id for the state session as parameters. =head2 Embperl_Useenv =over =item Env: EMBPERL_USEENV =item Method: $component -> config -> use_env I<[read only]> =item Default: off unless runing as CGI script =item Since: 2.0b6 =back Tells Embperl to scan the enviromemt for configuration settings. =head2 use_redirect_env =over =item Method: $component -> config -> use_redirect_env I<[read only]> =item Default: off unless runing as CGI script =item Since: 2.0b6 =back Tells Embperl to scan the enviromemt for configuration settings which has the prefix C. This is normally the case when the request is not the main request, but a subrequest. =head2 Embperl_Package =over =item Env: EMBPERL_PACKAGE =item Method: $component -> config -> package =back 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.) =head2 Embperl_Debug =over =item Env: EMBPERL_DEBUG =item Method: $component -> config -> debug =back See application configuration for an describtion of possible values =head2 Embperl_Options =over =item Env: EMBPERL_OPTIONS =item Method: $component -> config -> options =back This bitmask specifies some options for the execution of Embperl. To specify multiple options, simply add the values together. =over 4 =item optDisableVarCleanup = 1 Disables the automatic cleanup of variables at the end of each request. =item 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. =item 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 I 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 C<$errors> is a array reference. (1.3b5+) =item optShowBacktrace = 0x8000000 When set every error message not only show the sourcefiles, but all files from which this file was called by Execute. =item 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 L<"(Safe-)Namespaces and opcode restrictions"> below for more details.) =item optOpcodeMask = 8 Tells Embperl to apply an operator mask. This gives you the chance to disallow special (unsafe) opcodes. (See the Chapter about L<"(Safe-)Namespaces and opcode restrictions"> below for more details.) =item 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). =item optFormDataNoUtf8 = 0x2000000 By default Embperl checks all formfields in %fdat if they contain valid UTF-8 strings and if yes sets Perl's internals UTF-8 flag. If this option is set Embperl will never set the UTF-8 on any data in %fdat. =item 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. =item optRedirectStdout = 16384 Redirects STDOUT to the Embperl output stream before every request and resets it afterwards. If set, you can use a normal Perl B 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 B. =item 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 B. When this option is set, Embperl will not output a hidden input element for this field when the value is a blank string. =item 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. =item optChdirToSource = 0x10000000 (only 2.5 and above) Change current working directory to the directory of the sourcefile, before executing the source. =back =head2 Embperl_Escmode =over =item Env: EMBPERL_ESCMODE =item Method: $component -> config -> escmode =item Default: 7 =back Turn HTML and URL escaping on and off. NOTE: If you want to output binary data, you must set the escmode to zero. For convenience you can change the escmode inside a page by setting the variable C<$escmode>. =over 4 =item escXML = 8 (or 15) (2.0b4 and above) The result of a Perl expression is always XML-escaped (e.g., `>' becomes `>' and ' become '). =item escUrl + escHtml = 3 (or 7) The result of a Perl expression is HTML-escaped (e.g., `>' becomes `>') in normal text and URL-escaped (e.g., `&' becomes `%26') within of C, C, C, C