<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="16. Runtime Hosting" />
<meta name="dc.subject" content="16. Runtime Hosting" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="runtimehosting.html" title="Chapter Contents" />
<link rel="prev" href="cinterface.html" title="Virtuoso Server Extension Interface (VSEI) (C Interface)" />
<link rel="next" href="contents.html" title="Contents" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>16. Runtime Hosting</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="vseplugins" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>16. Runtime Hosting</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="runtimehosting.html">Chapter Contents</a> | <a class="link" href="cinterface.html" title="Virtuoso Server Extension Interface (VSEI) (C Interface)">Prev</a> | <a class="link" href="internetservices.html" title="Internet Services">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div class="selected">
<a href="runtimehosting.html">Runtime Hosting</a>
</div>
<br />
<div>
<a href="rthactivation.html">Runtime Environments</a>
</div>
<div>
<a href="rthclr.html">CLR, .Net & ASPX Host</a>
</div>
<div>
<a href="rthclrmono.html">CLR & Mono</a>
</div>
<div>
<a href="javaextvm.html">Embedded Java VM API</a>
</div>
<div>
<a href="cinterface.html">Virtuoso Server Extension Interface (VSEI) (C Interface)</a>
</div>
<div class="selected">
<a href="vseplugins.html">VSEI Plugins</a>
</div>
<br />
</div>
<div id="text">
<a name="vseplugins" />
<h2>16.6. VSEI Plugins</h2>
<p>Virtuoso functionality can be enhanced through external libraries by
loading shared objects or DLLs. The new functions are written in a language of
the developer's choice and compiled to produce a shared library appropriate to the operating
system. The path to the shared library must be declared in the Virtuoso INI
file and the server restarted before it can be used.</p>
<p>The Virtuoso INI file uses a [Plugins] configuration section for listing
shared libraries for the server to load upon startup. The layout is as
follows:</p>
<div>
<pre class="programlisting">
[Plugins]
LoadPath = <module path> (example : /home/virtuoso/hosting)
Load1 = <module type>, <module name> (example : hosting_perl.so)
Load2 = <module type 2>, <module name 2>
..
LoadN = <module type N>, <module name N>
</pre>
</div>
<p>Virtuoso reads the Load1, Load2, ... LoadN lines from the [Plugins]
section and attaches them according to their type. </p>
<p>
<span class="computeroutput"><module path></span> is the directory
containing shared modules for use with Virtuoso. (e.g. <span class="computeroutput">/home/virtuoso/hosting</span>)</p>
<p>
<span class="computeroutput"><module type></span> specifies the type of
module that is to be loaded, and hence how Virtuoso is to use it. So far only
the "Hosting" type exists. </p>
<p>
<span class="computeroutput"><module name></span> is the file name of
the modules shared library or object.
(e.g. <span class="computeroutput">hosting_perl.so</span>)</p>
<p>The "Hosting" type defines entry points for initialization of the runtime
hosting environment, destruction of the user environment and execution of a
file or string containing commands in the hosted language. It also returns a
list of file extensions that it is capable of processing. Virtuoso
dynamically defines memory-resident (no disk image) HTTP server handlers for
each specified type. For example, the Perl hosting plugin supports 'pl'
extension. Hence, upon initialization of the hosting plugin, Virtuoso defines
the <span class="computeroutput">__http_handler_pl(..)</span> function according to the API
for file type handlers in the Virtuoso HTTP server. With this handler in place,
each hit on a .pl file (file system or WebDAV) with appropriate execute
permissions will cause the HTTP server to execute the code within it and return
the result instead of simple the file contents.</p>
<p>The handler will call the __hosting_http_handler VSE with a special set
of parameters to represent the HTTP environment correctly.</p>
<p>There's a VSE to call each of the hosting modules:</p>
<p>
<span class="computeroutput">__hosting_http_handler (
in <span class="parameter">extension</span>, varchar,
in <span class="parameter">content</span>, varchar,
[in <span class="parameter">params</span>, varchar, ]
[in <span class="parameter">lines</span>, any, ]
[inout <span class="parameter">filename_head_ret</span>, varchar, ]
[in <span class="parameter">options</span>, any, ]
[out <span class="parameter">diag_ret</span> varchar]) returns varchar</span>
</p>
<p>such that:</p>
<table class="varlist">
<tr>
<td align="right" valign="top" class="varterm" nowrap="nowrap">extension:</td>
<td>
<p>Selects plugin by supported extension handler. e.g. pass 'pl' for the perl plugin.</p>
</td>
</tr>
<tr>
<td align="right" valign="top" class="varterm" nowrap="nowrap">content:</td>
<td>
<p>If <filename_head_ret> is NULL or unspecified this
will be the name of the file containing the code to execute in the hosted
environment, otherwise this will be program code to execute as a string.</p>
</td>
</tr>
<tr>
<td align="right" valign="top" class="varterm" nowrap="nowrap">params:</td>
<td>
<p>(optional) A string containing the HTTP parameters as encoded
in the HTTP request body.</p>
</td>
</tr>
<tr>
<td align="right" valign="top" class="varterm" nowrap="nowrap">lines:</td>
<td>
<p>(optional) A vector (array) containing the HTTP request headers, in
the same format as those passed to VSPs.</p>
</td>
</tr>
<tr>
<td align="right" valign="top" class="varterm" nowrap="nowrap">filename_head_ret:</td>
<td>
<p>(optional) On input this is the "name" to put on the command
text passed in <content>. If this is NULL it means that <content>
holds the path and filename containing the commands. On output this contains
the HTTP headers of the HTTP response generated by the plugin, if any and
in HTTP mode.</p>
</td>
</tr>
<tr>
<td align="right" valign="top" class="varterm" nowrap="nowrap">options:</td>
<td>
<p>(optional) A vector holding name/value pairs of strings
passed as options to the plugin. The Perl plugin sets
the other options as environment variables before calling the perl code.</p>
<p>There is a "<span class="computeroutput">__VIRT_CGI</span>" =
"<span class="computeroutput">0</span>"/"<span class="computeroutput">1</span>" option
to control whether the plugin operates in HTTP mode
(<span class="computeroutput">__VIRT_CGI=1</span>) i.e. implements the CGI
interface and treats the output as an HTTP response.</p>
</td>
</tr>
<tr>
<td align="right" valign="top" class="varterm" nowrap="nowrap">diag_ret:</td>
<td>
<p>(optional) Returns various diagnostics messages returned
while the code is running if any. The perl plugin sets this to the collected
STDERR messages.</p>
</td>
</tr>
</table>
<p>The function will return a varchar containing the HTTP body if in HTTP mode
(<span class="computeroutput">__VIRT_CGI = 1</span>) or the messages printed to
STDOUT.</p>
<p>Virtuoso will normally call to memory each plugin as required, and expel
it when finished. This behavior can be controlled by the INI file parameter:</p>
<div>
<pre class="programlisting">
[HTTPServer]
PersistentHostingModules = 1/0 default 0
</pre>
</div>
<p>Setting <span class="computeroutput">PersistentHostingModules</span> to "1"
prevents Virtuoso from removing the interpreters from the HTTP threads after
each request.</p>
<a name="ex_plugshostingsharedobjects" />
<div class="example">
<div class="exampletitle">Using the Perl Plugin</div>
<p>Executing Perl code directly:</p>
<div>
<pre class="programlisting">
select __hosting_http_handler ('pl', 'print "hello world"; ', '', vector (), 'helloworld.pl');
</pre>
</div>
<div>
<pre class="programlisting">
returns : hello world
</pre>
</div>
<p>Executing a perl script file (perl/test_print.pl in the Virtuoso
working directory):</p>
<div>
<pre class="programlisting">
/perl/test_print.pl
-------------------
#!/usr/bin/perl
print "hello world file";
</pre>
</div>
<div>
<pre class="programlisting">
select __hosting_http_handler ('pl', 'perl/test_print.pl');
</pre>
</div>
<div>
<pre class="programlisting">
returns : hello world file
</pre>
</div>
</div>
<div class="note">
<div class="notetitle">Note:</div>
<p>The hosting_perl hosting module uses the perl <span class="computeroutput">tie()</span>
function to "tie" up the STDIN, STDOUT, STDERR, exit() and %ENV perl objects.
Untying any of these may lead to unpredictable results.</p>
</div>
<table border="0" width="90%" id="navbarbottom">
<tr>
<td align="left" width="33%">
<a href="cinterface.html" title="Virtuoso Server Extension Interface (VSEI) (C Interface)">Previous</a>
<br />Virtuoso Server Extension Interface (VSEI) (C Interface)</td>
<td align="center" width="34%">
<a href="runtimehosting.html">Chapter Contents</a>
</td>
<td align="right" width="33%">
<a href="internetservices.html" title="Internet Services">Next</a>
<br />Contents of Internet Services</td>
</tr>
</table>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
982
