The dispatcher is the logic object, which is loaded once by the server object and executed for each connection. This object will handle basic HTTP configuration stuff at startup time like MIME-mappings and general functionality per physical connection like Keep-Alive behaviour. The main functionality is to distribute the request to the several logical handlers, which are configured for the dispatcher.

Option Default Values Short Description Example(s)
AddMIMEEntry - "<ext>SP<MIME-type>" To register mime entry by server AddMIMEEntry "exe application/octet-stream"
KeepOpen - "On","Off" Control, if a physical connection is reused by multiple logical requests KeepOpen "On"
KeepOpenCount - nnnn Number of reuses of physical connection KeepOpenCount 100
KeepOpenTimeout - n seconds or -1 (infinite) Timout for physical connection between logical requests KeepOpenTimeout 5
ServerRoot - absolute or relative path Root directory of the server ServerRoot ./../
ServerStamp - Any string Server name stamp used in headers ServerStamp Pi3Web/2.0.0
DefaultHost - An configured virtual host object Logical host used per default DefaultHost MainVirtualHostInformation
MIMEFile - Valid name of an existing file A file containing mime entries MIMEFile "Fragment/Mime.typ"
ErrorLogFile - A valid file name A file to write error logs ErrorLogFile "Logs/error.txt"
DebugLogFile - A valid file name A file to write debug logs DebugLogFile "Logs/debug.txt"
DebugBeforeHandler - A Pi3Expression An expression to log before a handler is called DebugBeforeHandler "[$P:$k] &align(,$X)&align(,$X) |--> $T -------- &align($N,12) &align($R,12) $n \"$r\" $s"
DebugAfterHandler - A Pi3Expression An expression to log after a handler is called DebugAfterHandler "[$P:$k] &align(,$X)&align(,$X) |<-- $T &align($D,8) &align($N,12) &align($R,12) $n \"$r\" $s"
- in the default indicates no default
+ in the default indicates the field is mandatory

Description of Options

The respective MIME type will be registered in the server. If a resource with the same extension is retrieved by a request, the Content-Type header will be set to the appropriate MIME-type.
This flag determines, if a physical connection could be reused through multiple logical connections (HTTP request/response pairs). This could significant increase the performance. The default value is "On". But it also depends on the headers sent by the client if actual the Keep-Alive protocol is used.
The optional value determines the maximum number of connection reuses. This is useful, because otherwise the server would not fall through to the process and thread handling routines, which would kill a process after a number of requests. This number is configured per server process, because Pi3Web logic may have and some OS libraries actual have significant memory leaks (Solaris). The default value is 100.
The optional value determines the timeout value between the requests of a reused physical connection. This timeout value should be selected shorter than the general IO receive timeout configured with the TCPIOObject. The default timeout value is 5 seconds.
The relative or absolute path specifies the root directory of the server. All relative paths used in mappings will be in relation to this directory. However, it is not possible to look above the ServerRoot with "special" URLs like "/..". If a relative path is given as ServerRoot, the resulting path is relative to the startup directory (normaly ./Pi3Web/bin),
The string you set as ServerStamp is sent back to the client in the respective HTTP response header. Several companies watch to the internet and the server activities. Their statisitcs are based on the ServerStamps they get back from the web hosts.
The value must point to a valid virtual host object. This object is used per default, if no other mapping occurs during request phase HOSTMAP.
This is an alternative way to configure the MIME-type mapping of the Pi3Web server. The file must contain one MIME-Mapping per line specified in the format
# Comment
application/octet-stream    bin dms lha lzh exe class
application/pdf             pdf
The optional specified file will be used to write server error log information. If the file does not exist it will be created. If the file exists it will be overwritten. By omitting this option the error log will be switched off.
The optional specified file will be used to write server debug log information. If the file does not exist it will be created. If the file exists it will be overwritten. By omitting this option the debug log will be switched off. Because debug log is very expensive it should not be used with a production server. It is intended to use for development, performance optimization and troubleshooting purposes only.

The format of the log entries is specified by the options DebugBeforeHandler and DebugAfterHandler. Per handler call 2 debug entries will be written before and after the handler is executed. If nested handlers are called, the corresponding debug log lines are indented.

This Pi3Expression specifies the line which is logged before a certain handler is called.
This Pi3Expression specifies the line which is logged before a certain handler is called.

All phases

The execute function of the Dispatcher object will return either PIAPI_COMPLETED, PIAPI_ABORT or PIAPI_ERROR according to the status returned by the logical extensions (handlers).



		Name HTTPLogicObject
		Class HTTPDispatcherClass

		Handlers Start Scripts Default

		AddMIMEEntry "xls	application/msexcel"
		AddMIMEEntry "xlt	application/msexcel"
		AddMIMEEntry "doc	application/msword"
		AddMIMEEntry "bin	application/octet-stream"
		AddMIMEEntry "dms	application/octet-stream"
		AddMIMEEntry "lha	application/octet-stream"
		AddMIMEEntry "lzh	application/octet-stream"
		AddMIMEEntry "exe	application/octet-stream"
		AddMIMEEntry "imap	internal/x-imagemap"
		DefaultMIMEType "application/octet-stream"

		KeepOpen "On"
		KeepOpenCount 100
		KeepOpenTimeout 5

		ServerRoot ./../
		ServerStamp Pi3Web/2.0.0
		DefaultHost MainVirtualHostInformation
#		MIMEFile "Fragment/Mime.typ"
		ErrorLogFile "Logs/error.txt"
#		DebugLogFile "Logs/debug.txt"
		DebugBeforeHandler "[$P:$k] &align(,$X)&align(,$X) |--> $T \
-------- &align($N,12) &align($R,12) $n \"$r\" $s"
		DebugAfterHandler "[$P:$k] &align(,$X)&align(,$X) |<-- $T \
&align($D,8) &align($N,12) &align($R,12) $n \"$r\" $s"



A Pi3Expression is a general purpose expression syntax for efficient dynamic creation of text based on varied criteria. The expression takes the form of a sequence of text characters with some control characters which modify the meaning of the text which follows them. A Pi3Expression does not have to be enclosed in quotes but often will be quoted in configuration files to deliniate the expression from other configuration components. For illustration all examples used here will enclose the example expression in double-quotations ("").


Component Syntax Short Description Example Expression Example Result
String Any character except $,%,& Plain text "Hello, World!" Hello, World!
Escape Sequences \c, where c is any character Escaped charcaters, like printf format "Line1\nLine2" Line1
Literal 'any characters' Literal text, characters not interpreted. "The percent character is '%'" The percent character is %
Parameter %c, where c is a letter A parameter, value depends on Pi3Expression context "Parameter value of parameter ''v'' is ''%v''" Parameter value of parameter 'v' is 'john'
Shortcut $s, where s is a letter A shortcut, shortcut value mappings are given below "The current process id is $P" The current process id is 24456
Functions &FunctionName(Param1,Param2,..,ParamN) A text processing function, described in 'Pi3Expression_Functions' "Process id truncated to two characters is &trunc($P,2)" Process id truncated to two characters is 24

Detailed Description of Components

Regular text that does not conform to other expression components is reproduced exactly if the expression result as in the expression string. The characters '(', ',', and ')' are considered normal characters outside a function context.
Escape Sequences

The escape or backslash character will be expanded to a control character in accordance with the following table:

Escape Sequence Meaning
\a Alert
\b Backslash
\f Form-feed
\n New-line
\r Carriage return
\t Horizontal tab
\v Vertical tab
Additionally any other character including characters with special meanings in Pi3Expressions ($,%,&,\,´) can be specified by placing ´\´ before them.
Character sequences enclosed in single quotes will be reproduced in the expression result as in the expression specification, but with the single quotes ommitted.
The '%' character followed by a letter specifies a parameter. The value of a parameter depends on the evaluation context and should be documented along with the facility that uses the expression. Parameter characters are case sensitive.
The '$' character followed by a letter specifies a shortcut. Shortcut characters are case sensitive. The follow table gives shortcut mappings.
ShortcutEvaluates to
$aE-mail address of administrator (for current virtual host)
$AIP Address of remote client
$bDecimal representation of number of bytes sent to client this request
$cContent-Type for the response
$CContent-Type for the request (incoming)
$dDebug flag, returns non-zero length string if debugging is on
$DHandler time delta. Time spent in last handler object
$eSSL cipher name
$EAll error messages logged while handling this (sub)request
$fPhysical path to resource
$gIndicate whether or not SSL is being used (HTTPS), (on/off)
$GSSL secret key size
$hHostname of client
$HRequest HTTP protocol stamp
$iRemoteident of client
$IPath info section of client request URL
$kThread id of executing thread of execution
$KSSL public key size
$lLocal IP address of connection
$mRequest method from client
$MEnd of line sequence for the current operating system
$nName of current handler object
$NName of current handler phase
$oObjectname of virtual host
$pPort associated with this virtual host
$PProcess id
$qClient query string
$rFull uninterpreted request line from client
$RName of result code from last handler
$sCurrent decimal HTTP response status code
$SServer version stamp
$tTime in common logfile format
$TElapsed since request context (PIHTTP) was created
$uRemote username (from authentication)
$UURL path of original request
$vHostname of virtual host
$xAuthentication type from is access was authenticated
$XDepth of current request in subrequest hierarchy
$yContent-Length: outgoing to client
$YContent-Length: incoming from client
$zScript name
$ZPath translated (url-unencoded path info)
The built-in text manipulation functions are described in the section 'Pi3Expression_Functions'.


ExpressionProcess/Thread information [$P|$k]
Evaluates toProcess/Thread information [24965|23]
Evaluates to|15/May/1997:21:30:16 +0000|caught.evil.dom|GET /../etc/passwd HTTP/1.0



Pi3Expressions can use built in functions for text manipulation and conditional processing. These functions can be nested to perform complex evaluations. The built-in text processing functions are described here. Where text is interpreted as a numeric value, leading whitespace is skipped, then the text before the first non-digit is interpreted as a decimal number. Where text is interpreted as a boolean value, any non-zero length is considered 'true' and any text of length zero is considered 'false'.



Note the following conventions used to describing these functions:
text - any text, e.g. "foo", "234'&'ad" number - text interpreted as a number, e.g. "5a" (interpreted as 5). [field] - an optional argument value1|value2 - either "value1" or "value2" as text, e.g left|right
Function Number of Arguments Syntax Short Description Example Expression Example Result
abbrev 3 &abbrev(text,number,ellipse) truncate text and append other text if truncated "&abbrev(Abcdef,7,...)"
align 2..4 &align(text,number,[left|right],[padding]) Align text within a field "&align(1234,7)"
"1234   "
arg,_ 0..2 &_([index],number) Function argument "&_(0,0)"; &arg(1) context dependent
cmp 2 &cmp(text1,text2) String comparision "&cmp(hello,Hello)" ""
cmpi 2 &cmpi(text1,text2) String comparision case insensitive "&cmpi(hello,Hello)" "true"
dblookup 3..7 &dblookup(dbname,type,variable[,flags][,fnvalue][,first][,last]) Lookup a value in an internal database "&dblookup(request,rfc822,Content-Type)" "application/x-www-form-urlencoded"
dbreplace 3..7 &dbreplace(dbname,type,variable,value[,flags]) Replace a value in an internal database "&dbreplace(request,rfc822,Content-Type,text/html)" "text/html"
if 2..3 &if(boolean,true_text,false_text) Conditionally include text "&if(text,yes,no)"
not 1 &not(boolean) Negate boolean argument "&not(text)"
regexp 2 &regexp(regexp,text) Regular expression comparision "&regexp(j*n,john)"
trunc 2 &trunc(text,number) Truncate text to length of number "&trunc(0123,2)" "01"

Detailed Description of Functions

This function is used to truncate text to a field of fieldlen characters appending text 'append' at the end of the field if it was truncated, this is useful for truncating test to fit in a field while given a clear indication if the field was concatenated.
Write text 'text' into a field of length characters, aligning to the left or right. The character sequence padding is repeated to fill out the field. The default alignment is left. The default padding is spaces. If 'text' is longer than the value of 'length', it will not be truncated.

A field of exactly 'length' character can be ensured by using an expression like:
&align(&trunc(text is too big,10),10)

This is a special function with meaning only within the context of another function which is iterating through a number of elements. The argument 'index' is the index of the argument from the enclosing function. The argument context is a number indicating the which enclosing functions context to use. Context 0 refers to the callees context, 1 to the callees callee etc.
cmp(text1,text2), cmpi(text1,text2)
Respectively case sensitive and insensitive comparision of two text patterns.
NOTE:This function is not currently supported to the full specification as described here. Iterate over a number of elements of a specific type in a particular database.

Function arguments:
Argument position Description Default, (+)=Mandatory Values
1 name of database + program|connection|host|request|response
2 type of element + rfc822|string|opaque
3 variable name + a variable name (or empty for all)
4 db flags affecting lookup 0 pidbflag_propagateup|pidbflag_fastkey|0
5 callback argument &_() Expression invoked for value of every db entry
6 start index 0 Number
7 end index 0 Number

Replace the value of a variable of the specific type in a particular database. The function arguments are the same as described above.
If boolean is true (i.e., boolean is any character sequence with length greater than zero), then this function evaluates to true_text, otherwise this function evaluates to false_text.
If boolean is true (i.e., boolean is any character sequence with length greater than zero), then this function returns a zero length text string (false), otherwise a non-zero length text string (true) is returned. The net result is the negation of the boolean argument.
Determine if the regular expression 'regex' matches the text 'text'. Returns 'true' (non-empty text) on success, 'false' (empty text) on failure. Regular expression matching is done using the function HTTPUtil_regexMatch(), reference that function to see which regular expression constructs which are supported.
Truncate text to the the decimal value of number.