Configuration Options

The main configuration file allows tuning essential options within the processor. In some cases, bad values may result in a processor not functionning at all, or processing the pages in a strange way. It may be the case on an Unix/Linux system, if configuration option sets a policy that is contradictory to local system security settings.

PHP	$ESSI_root
Value	path_to_absolute_root

The absolute root "DocumentRoot" of the server where pages processed by this processor are standing. Note that this version of the processor cannot work on aliased volumes without an explict declaration in the $aliases table of the configuration file.

(Reason was the mod_rewrite Apache module, that does not provide the relative URI of the targetted DIML document, and let the processor assume its only location is being related to the DocumentRoot).

PHP	$ESSI_Straight
PERL	$main::STRAIGHT
Value	true|false|redirect

If ESSI_Straight is "true", the DIML processor is called directly using its CGI script location. The DIML source to be processed must then be provided as an additional CGI argument "ESSI_TARGET" and MUST be relative to DocumentRoot.

If ESSI_Straight is "false", this tells the processor is implicitely routed for genuine MIME type (x-application/essi-parsed).

When set to "redirect", the processor has to be called through an URL rewriting indirection. This is always true in PHP.

PHP	$ESSI_StraightBackPath
PERL	$main::STRAIGHT_BACKPATH
Value	relative_path_to_DocumentRoot_location

When the processor is called as a direct CGI script, it needs knowing the location of the DocumentRoot relatively to its own script location. For example, if this script is located in the /wwwroot/cgi-bin/essi_processor/ directory, and DocumentRoot is /wwwroot, the value for this parameter should be "../../".

PHP	$ESSI_Standalone
PERL	$main::STANDALONE
Value	true|false

Should be set to "true" only ifthe processor is to be used as a Perl library for another application. This switches off the parsing of the CGI input string (CGI parameters might be used in other context in the application, and are assumed to be provided to the processor through the standard $main::ESSInput hash).

PHP	$ESSI_NoInvoke
PERL	$main::NOINVOKE
Value	true|false

An essential option in a non secure situation. It will allow using paramtrization power of the DIML, without allowing users to overscript the DIML pages. It may be a good idea when users may be not under control. On "true", the invoke statement is disabled.

PHP	$ESSI_TraceLevel
PERL	$main::TRACE_LEVEL
Value range	0 - 30

Sets the trace level. The DIML trace control allows watching some major control points, checkpoints in overscripting, up to an allmost instruction by instruction examination. A level of 0 doesn't create any trace output. The higher the level, the more precise the trace is, and of course, the fatter it is. Here are some key levels that can be used:

• 0 : No trace
• 1 : Processor headers (version, document location, time)
• 2 : Adds known variables (CGI inputs + ESSI Internal context variables)
• 4 : Adds known vars, allows tracing checkpoints of level 1,2,3 in overscriptings, and tell variables that appeared or desapeared before and after the overscripting invocation.
• 5 : Adds page construction process information (individual parsing of each statement) in an auto indented manner.

PERL	$main::TRACE_TOPICS
Value	list_of_topics

Implemented only in Perl. Allows selecting trace outputs by topics, independently from the trace level filtering. This parameter may contain a comma separated list of topics. Each topic may be negated by a "!" prefix, causing all outputs for this topic being avoided, even if the trace level setting would have allowed them.

PHP	$ESSI_MaxDepth
PERL	$main::MAX_SCAN_DEPTH
Value	entier
Typical	20

This is a setting of a mechanism that avoids infinite recursion within the processor. Consider the case a template <%%A%%> would, directely or indirectely call itself, the processor might recurse indefinitely. This value sets a "hardware" limitation of how many recursions the processor can accept. For 5 years we are using the processor, we did never use a value over 20, although it may depend on the programming "style" of the developper. Some templates using controlled recursion (such as forum message trees) might need higher values.

PHP	$ESSI_OutputType
PERL	$main::OUTPUT_TYPE
Value	mime_type
Default	text/html

Defines the output content type the processor produces. This preset may be overloaded in the DIML document by setting a new value for the %ESSI::OUTPUT_TYPE% global entry.

PHP	$ESSI_LogFileName
PERL	$main::LOG_FILENAME
Default	essi.log

The name for the trace file.

This name might be parametric for each DIML source, e.g.:

(PERL)
$doc_name = $ENV{"REDIRECT_URL"};
$doc_name =~ s/.*?([^\/]+)\.[^\/.]+$/$1/;
$main::LOG_FILENAME = "essi_" . $doc_name . ".log";

PHP	$ESSI_LogPositionning
PERL	$main::LOG_POSITIONNING
Value	relative|absolute

When set to "relative", the trace file is written at a subpath equivalent to the relative offset of the DIML source from DocumentRoot.

When set to "absolute" and the LogRoot is set to an explicit absolute path, then the trace file is written at this exact location. This setting should be avoided on an explotation server because it may concentrate trace writing activity of numerous client threads on the same resource and no access conflict is arbitrated by the processor.

PHP	$ESSI_LogRoot
PERL	$main::LOG_ROOT
Value	physical_path
Default	""

Fixes an absolute root for the trace outputs. If empty, the trace files are writtent in the same location the DIML source stands. If it is set to a non empty path, files may be written at a unique location (LogPositionning "absolute") or in a parallel path architecture (LogPositionning "false"). Check in that last case that the processor has sufficient access priviliedges to create files and folders from this new root.

PHP	$ESSI_ParsingMarkers
PERL	$main::PARSINGMARKERS
Value	on|off

When set to "on", the processor adds HTML comments to the output flow, in order to help identifying some non linear constructs (e.g. scripts and style recollection). We noticed that some syntaxes of comments could perturbate definitions of some style rules. If such issues occur, leave this parameter on "off".

PHP	$ESSI_TimeBenchFile
PERL	$main::TIME_BENCH_FILE
Value	file_name
Default	essi.bnc

Sets the name form the time benching report file. This file can only be written at the same location than the DIML source. It is required the server may have write permission in this dirs. This feature will then be strongly discouradged on effective implementations.

Note that time calculation uses the Time::Hires module that is not provided by the default distribution of ActivePerl. Use PPM utility to install this library.

PHP	$ESSI_TimeBench
PERL	$main::TIME_BENCH
Value	on|off

Enables or disables the time benching.

PHP	$ESSI_LoadedModules
PERL	@main::LOADED_MODULES
Value	module_name_table

A table that tells which extension modules to be loaded into the processor. An extesion module adds additional parsing capabilities to the DIML,and allows third party syntactic extentions. The table is to be defined according to the current programming language (PHP or PERL) :

PHP:

$ESSI_LoadedModules = array("ESSISql", "ESSIXml");

Perl:

@main::LOADED_MODULES = ("ESSISql", "ESSIXml");

PHP	$ESSI_ImportFirstMatch
Value	on|off

Import optimisation:
When activated, and when the local part of the import definition has no wildcards, the first template matching the pattern will stop the search.

PHP	$ESSI_Aliases
Value	on|off

Aliases:
In PHP, the processor must have an explicit declaration of aliases. This is because of the Apache mod_rewrite URL rewriting model. As URL rewrite is performed before any physical transposition, Apache cannot tell the processor the effective physical location of the required DIML source. The ESSI processor is required to use a relative URI path, and should proceed itself to the aliasing.

Setting this paramter to "on" activates the aliasing process.

PHP	$ESSI_Alias
Value	alias_defs_hash

If aliasing is activated, this hash should contain an entry for all aliases declared within the Apaches httpd.conf file.

e.g.:

$ESSI_Alias['/diml/'] = "/diml_new/";