14.3. Virtuoso Server Pages (VSP)
The Virtuoso Server Pages subsystem is an integral part of the Virtuoso server. A VSP page is a file system or DAV resident resource that contains Virtuoso/PL code intermixed with HTML or other static content.
Figure 14.14. VSP Conceptual Diagram
Virtuoso can serve Web pages to HTTP 1.0 and HTTP 1.1 clients.
The HTTP document root is set by the ServerRoot parameter in the
[HTTPServer] section of the Virtuoso INI file. By default this is
vsp sub-directory of the
installation. If this parameter is not set, then the default
document root will be the server's working directory.
Executing VSP Pages. Directories under
the ServerRoot directory, including the root itself are not
automatically allowed to execute dynamic pages such as VSP. A
virtual directory must first be created with an appropriate VSP
user assigned to permit execution of dynamic pages. After this,
Virtuoso will execute files with a "
.vsp " extension as a VSP page.]
The VSP Stored Procedure. Each VSP page
constitutes a Virtuoso stored procedure named after the URI of the
page by taking the URI and pre-pending the WS.WS. qualifier and
owner. Hence the page
becomes the procedure
"WS"."WS"."/test.vsp" . This is
automatically performed when a page is first requested. Subsequent
requests to the page will not reference the file. The VSP engine
will check for changes in the
.vsp source file before calling the
procedure and re-compile as required. The ws_proc_def() SQL
function can be used to explicitly update the procedure if the .vsp
file is changed.
The VSP Transaction. Each URL is executed
in its own transaction. All SQL statements in a page procedure,
whether on local or remote data, make up one transaction, unless
transaction control statements are explicitly used to divide the
page into multiple transactions. If the page procedure returns
through completing execution or through a return statement or as a
result of a 'no data found' condition, the transaction is
implicitly committed. If this commit fails, the output is discarded
and the error message indicating the commit failure is sent to the
HTTP client. If a VSP procedure returns as a result of an error the
transaction is rolled back and the output discarded. The client
gets the SQL error message as the HTML body of the reply. A VSP
procedure can commit or roll back explicitly with the
commit work or
rollback work PL statements.
If the client closes the connection to the server while server-side processing is taking place this will be detected by the server and the transaction will be eventually interrupted and rolled back in the same way as if an ODBC client had disconnected. To control the server reacting or not on the HTTP client disconnecting the SET HTTP_IGNORE_DISCONNECT = ON/OFF should be used.
Each VSP page-procedure is called with three arguments:
|path - the URI path of the VSP page itself.|
|params - the parameters from a previous POST to the server.|
|lines - the complete set of headers received from the calling client.|
Each VSP procedure runs in a context that implicitly contains the stream to the HTTP client. The arguments of the VSP page procedure are represented as arrays of strings. For example, GETing the URL:
would cause the following arguments to be given to the
path ('x', 'y.vsp') params ('arg1', '1', 'arg2', '2') lines ('GET /x/y.vsp?arg1=1&arg2=2 HTTP/1.1', 'Host: www.test.net', ...)
Arrays are marked in parentheses with elements separated by commas. The page procedure is called as a result of either a GET or POST request in either HTTP/1.0 or HTTP/1.1. In the event of a POST request the params contains the post data.
Virtuoso can be configured to proxy certain requests to another web server. This allows using another web server for running cgi-bin's, Java servelets or other web server functions. Virtuoso, however, is capable of hosting many other dynamic engines also, such as PHP, JSP and ASP.Net.