DSP - Data Server Pages

Overview

DSP stands for Data Server Pages, the Apache HTTP Server module, that provides PL/SQL Server Scripting and features an efficient authorization and authentication framework on the Oracle database tier.

Features

PL/SQL Server scripting

Script preprocessor / variable injection

Efficient authentication / authorization framework

Flexible and easy configuration

Free software, open source

Components

mod_dsp apache module

DSP comaptible PL/SQL package

Server Requirements

Apache HTTP Server (Win32) >= 2.2

OCI (Oracle Call Interface) >= 9.2

Oracle database >= 8.1.5

Client Requirements

Session cookies, if authentication / authorization feature is enabled

Scripting Tags

ASP-style: <% and %>

XML-style: <?dsp and ?>

Examples

<% DSP.print('DSP Rocks!'); %>

<?dsp DSP.print('DSP Rolls!'); ?>

Scripting Blocks

Script blocks: <?dsp ... ?>

Quick blocks: <?dsp= ... ?>

Script blocks contain PL/SQL code and server variable placeholders.

Quick blocks contain only a server variable placeholder.

Note:

Quick blocks are quote-blind -- they can appear inside "quoted" text, such as HREF.

Script blocks are quote-aware -- they are ignored if inside "quoted" strings.

Script Block Example

<TABLE>

<?dsp

CLASS=tag><?dsp

DECLARE

CURSOR c_object IS

SELECT object_name name,object_type type

FROM user_objects;

BEGIN

FOR r_object IN c_object LOOP

DSP.write('<TR>');

DSP.write('<TD>'||r_object.name||'</TD>');

DSP.write('<TD>'||r_object.type||'</TD>');

DSP.print('</TR>');

END LOOP;

END;

</TABLE>

Variable injection

Sample	Block	Feature
{$ ... }	PL/SQL	SQL-Escape
{$ ... }	Quick	HTML-Escape
{@ ... }	Quick	URL-Escape
{ ... }	Any

Example

Script	Result
Who am I? I am <i><%= {USER} %></i>.	Who am I? I am JOE.

Server variables

Variable	Meaning
URI, URL	Request Uri
USER	Request/Session User
SERVER.admin	Server Admin
SERVER.host	Server Host
SERVER.ip	Server IP
SERVER.name	Server Name
SERVER.path	Server Path
CONTEXT.path	Context Path
CONTEXT.url	Context Url
CONTEXT.login_page	Context Login Page (DSP:LoginPage)
CONTEXT.logout_page	Context Login Page (DSP:LogoutPage)
CONTEXT.login_fail	Login Fail Page (DSP:LoginFail)
CONTEXT.login_pass	Login Pass Page (DSP:LoginPage)
SESSION.user	Session User
SESSION.timeout	Session Timeout
REQUEST.auth	Request/Session Auth. type
REQUEST.content_length	Request/Resource Content-Length
REQUEST.content_type	Request/Resource Content-Type
REQUEST.cookie	Request Cookie Header
REQUEST.file	Request File
REQUEST.host	Request/Server Host
REQUEST.ip	Request IP
REQUEST.is_local	Boolean TRUE for local request
REQUEST.method	Request HTTP Method
REQUEST.protocol	Request HTTP Protocol
REQUEST.referer	Request Referer
REQUEST.string	Request Unparsed uri
REQUEST.uri, url	Request Uri
REQUEST.user	Request User
PARAMETER[key]	Request Parameter (GET/POST)
COOKIE[key]	Request/Session Cookie
:[field]	Alias for CONTEXT[field]
::[field]	Alias for SERVER[field]
?[key]	Alias for PARAMETER[key]

Commands

{!EXIT} : Page drop-out

Authentication / Authorization (authnz)

DSP authentication / authorization it is built arround the concept of form-based authentication, where the credentials are supplied using HTML form.
The supplied credetials are then validated by a database stored procedure.

Directives to enable
DSP authentication / authorization

AuthType DSP

Require valid-user

DSP:AssentScript assent-script

In the form-based login paradigm, two special pages are defined: the login page and the logout page. In DSP two directives reflect this concept: the DSP:LoginPage and DSP:LogoutPage directive.

Additionally, a successull login triggers login-pass redirection,
and a failed login triggers login-fail redirection.

Login Trigger

HTTP request	DSP:LoginPage
Parameter	dsp	Required	Value 1
Parameter	page, pass	Optional	Overrides DSP:LoginPass
Parameter	fail	Optional	Overrides DSP:LoginFail
Parameter	user, name	Required	UserName
Parameter	key, pwd	Optional	Password

Logout Trigger

HTTP request	DSP:LogoutPage
or	Session timeout

Login Example

<TABLE>

<TR><TH>Login:

<TR><TD>Password: <TD><INPUT TYPE=password NAME=key>

</TABLE>

</FORM>

Directives

DSP:SessionTimeOut
Description	Time-out for DSP sessions.
Syntax	DSP:SessionTimeOut timeout-in-seconds
Default	DSP:SessionTimeOut 600
Context	Server

DSP:LoginPage
Description	Login Page
Syntax	DSP:LoginPage login-page
Example	DSP:LoginPage login.html
Context	Server, Directory
Note	Allways exempt from authnz

DSP:LogoutPage
Description	Logout Page
Syntax	DSP:LogoutPage logout-page
Example	DSP:LogoutPage logout.html
Context	Server, Directory

DSP:LoginPass
Description	Login Pass Page
Syntax	DSP:LoginPass <login-pass-page>
Example	DSP:LoginPass log-pass.html
Context	Server, Directory
Note	Allways subject to authnz

DSP:LoginFail
Description	Login Fail Page
Syntax	DSP:LoginFail <login-fail-page>
Example	DSP:LoginFail log-fail.html
Context	Server, Directory
Note	Allways exempt from authnz

DSP:ConnectString
Description	Oracle Connection String
Syntax	DSP:ConnectString oracle-connect-string
Example	DSP:ConnectString DSP/xxx@ORCL
Context	Server, Directory
Note	The oracle-user must be able to use DSP database objects.

DSP:AssentScript
Description	Authentication / authorization credential validation script
Syntax	DSP:AssentScript assent-scrpt
Default	BEGIN :1:= DSP.get_assent(:2,:3); END;
Example	DSP:AssentScript ":result:= DSP.get_assent(:name,:key);"
Context	Server, Directory
Note	Access is granted when result equals 1.
Function prototype: FUNCTION get_assent(v_name IN OUT NOCOPY VARCHAR, v_key IN VARCHAR) RETURN PLS_INTEGER; Note: The v_name parameter features input / output semantics. On output DSP expects a real user-name.

DSP:Match / DSP:AssentMatch / DSP:ScriptMatch

Description

Match rules for authnz and script

Syntax

DSP:Match match-rule ...

Default

DSP:Match +|*.html

Context

Server, Directory

Notes:

By Positive Filter: Item is included in processing.

By Negative Filter: Item is excluded from processing.

Match Examples:
Restrict access for PDF:	DSP:AssentMatch +\|*.pdf
Public access to main.html:	DSP:AssentMatch -\|main.html
Restrict text/xml and enable for scripting:	DSP:Match +\|:text/xml
Public access to x-.html* and enable for scripting:	DSP:AssentMatch -\|x-.html DSP:ScriptMatch +\|x-.html

Extra Notes:

Matching by Mime-Type is not completely implemented (yet).

If the requested resource is matched by any positive filter, mod_dsp attempts to:

disable caching of resource if match on DSP:AssentMatch

expire the resource on the client if match on DSP:ScriptMatch

Configuration Sample

LoadModule dsp_module mod/mod_dsp.so

DSP:ConnectString DSP/xxx@ORCL

DSP:SessionTimeOut 1800

# DBX

AuthType DSP

Require valid-user

DirectoryIndex main.html

ErrorDocument 403 /dbx/forbid.html

DSP:LoginPage login.html

DSP:LogoutPage logout.html

DSP:LoginPass welcome.html

DSP:LoginFail log-fail.html

DSP:AssentMatch -|main.html

</Location>

# DSPlus

DSP:ScriptMatch +|*.xml

</Location>

Limitations

There are some inherent limitations of DSP because of the very nature of tier layout and work partitioning.

Altough throughout the documentation the DSP PL/SQL scripting is referred to as server scripting, the more appropriate term could be remote server scripting -- note the keyword remote, as here indicates that the script itself executes outside of the web-server context. This implies limitations, such as:

Page drop-out, the {!EXIT} command, should not be used inside sub-routines.

No programmatic arbitrary server variable reference (e.g. iteration trough cookies or form parameters, also no access to variables by runtime names, etc)

The adequatelly educated user / developer should be aware of what mentioned above,
and be able to overcome limitations. Smart application modelling is of most importance.

Development Platform

Apache HTTP Server 2.2.0

Microsoft Windows XP Professional SP2

Oracle Database 8.1.5 & 10.2

OCI 10.2

Release Notes

Only Win32 version is available at this moment.

DSP applications may have additional client requirements. Please consult specific documentation.

DBX, DSPlus

DBX and DSPlus require Microsoft Internet Explorer

Features for the future

Improve HTTP POST application/x-www-form-urlencoded

Support for HTTP POST method multipart/form-data

Extend the PL/SQL framework to support Cookies, Statistics, CMS ...

Portability to other plaforms (C/C++ sources, build system)

Design some nice graphics (logo & icons)

Troubleshooting

Starting Apache fails with an error:
Syntax error on line line-number of apache/conf/httpd.conf: Cannot load mod/mod_dsp.so into server: The specified module could not be found:
Solution:
DSP module DLL dependecies could not be resolved. Most probably the PATH environment variable does not include the location of OCI libraries. Top-level mod_dsp dependencies include: msvcrt.dll, kernel32.dll, libapr-1.dll, libaprutil-1.dll, libhttpd.dll, oci.dll. Setup the system PATH environment to satisfy DLL dependecy resolution.

Starting Apache fails with an error:
Syntax error on line line-number of apache/conf/httpd.conf: Cannot load mod/mod_dsp.so into server: (127) The specified procedure could not be found:
Solution:
DSP Server Requirements were not met. Most probably an inappropriate OCI version is the cause of the problem. Satisfy the requirements and try again. If the problem persists contact the support.

Involvment

Read, use, learn, educate.
Report bugs, improvements, features.
Post reviews, ideas, requests, questions.
Mail, share, communicate, activate.

Links

SourceForge.net page: http://mod-dsp.sourceforge.net

SourceForge.net project: http://sourceforge.net/projects/mod-dsp

Apache Module registry: mod_dsp