Dispatcher
Pi3Expression
Pi3Expression_Functions

Description:
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.

Options:

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

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"

Description of Options

AddMIMEEntry

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.

KeepOpen

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.

KeepOpenCount

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.

KeepOpenTimeout

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.

ServerRoot

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

ServerStamp

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.

DefaultHost

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.

MIMEFile

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

ErrorLogFile

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.

DebugLogFile

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.

DebugBeforeHandler

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

DebugAfterHandler

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

Phase:
All phases

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

Note:

Example:


	<Object>
		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"
	</Object>

Name:
Pi3Expression

Description:
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 ("").

Components:

Overview

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 Line2
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

String

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.

Literal

Character sequences enclosed in single quotes will be reproduced in the expression result as in the expression specification, but with the single quotes ommitted.

Parameter

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.

Shortcut

The '$' character followed by a letter specifies a shortcut. Shortcut characters are case sensitive. The follow table gives shortcut mappings.

Shortcut	Evaluates to
$a	E-mail address of administrator (for current virtual host)
$A	IP Address of remote client
$b	Decimal representation of number of bytes sent to client this request
$c	Content-Type for the response
$C	Content-Type for the request (incoming)
$d	Debug flag, returns non-zero length string if debugging is on
$D	Handler time delta. Time spent in last handler object
$e	SSL cipher name
$E	All error messages logged while handling this (sub)request
$f	Physical path to resource
$g	Indicate whether or not SSL is being used (HTTPS), (on/off)
$G	SSL secret key size
$h	Hostname of client
$H	Request HTTP protocol stamp
$i	Remoteident of client
$I	Path info section of client request URL
$k	Thread id of executing thread of execution
$K	SSL public key size
$l	Local IP address of connection
$m	Request method from client
$M	End of line sequence for the current operating system
$n	Name of current handler object
$N	Name of current handler phase
$o	Objectname of virtual host
$p	Port associated with this virtual host
$P	Process id
$q	Client query string
$r	Full uninterpreted request line from client
$R	Name of result code from last handler
$s	Current decimal HTTP response status code
$S	Server version stamp
$t	Time in common logfile format
$T	Elapsed since request context (PIHTTP) was created
$u	Remote username (from authentication)
$U	URL path of original request
$v	Hostname of virtual host
$x	Authentication type from is access was authenticated
$X	Depth of current request in subrequest hierarchy
$y	Content-Length: outgoing to client
$Y	Content-Length: incoming from client
$z	Script name
$Z	Path translated (url-unencoded path info)

Functions

The built-in text manipulation functions are described in the section 'Pi3Expression_Functions'.

Examples:

Expression	Process/Thread information [$P\|$k]
Evaluates to	Process/Thread information [24965\|23]

Expression	[$t]$h\|$r
Evaluates to	\|15/May/1997:21:30:16 +0000\|caught.evil.dom\|GET /../etc/passwd HTTP/1.0

Name:
Pi3Expression_Functions

Description:
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'.

Functions:

Overview

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,...)"
"&abbrev(Abcdefgh,7,...)" "Abcdef"
"Abcd..."
align 2..4 &align(text,number,[left|right],[padding]) Align text within a field "&align(1234,7)"
"&align(1234,7,right,-)" "1234 "
"---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)"
"&if(,yes,no)" "yes"
"no"
not 1 &not(boolean) Negate boolean argument "&not(text)"
"&not()" ""
"true"
regexp 2 &regexp(regexp,text) Regular expression comparision "&regexp(j*n,john)"
"&regexp(b*l,john)" "true"
""
trunc 2 &trunc(text,number) Truncate text to length of number "&trunc(0123,2)" "01"

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,...)" "&abbrev(Abcdefgh,7,...)"	"Abcdef" "Abcd..."
align	2..4	&align(text,number,[left\|right],[padding])	Align text within a field	"&align(1234,7)" "&align(1234,7,right,-)"	"1234 " "---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)" "&if(,yes,no)"	"yes" "no"
not	1	&not(boolean)	Negate boolean argument	"&not(text)" "&not()"	"" "true"
regexp	2	&regexp(regexp,text)	Regular expression comparision	"&regexp(jn,john)" "&regexp(bl,john)"	"true" ""
trunc	2	&trunc(text,number)	Truncate text to length of number	"&trunc(0123,2)"	"01"

Detailed Description of Functions

abbrev(field,fieldlen,append)

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.

align(text,length[,left|right][,padding])

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)

arg([index],[context])

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.

dblookup(dbname,type,variable[,flags][,fnvalue][,first][,last])

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

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

dbreplace(dbname,type,variable,value[,flags])

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,true_text,false_text)

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.

not(boolean)

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.

regexp(regexp,text)

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.

trunc(text,number)

Truncate text to the the decimal value of number.