18.6. VSEI Plugins
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.
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:
[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>
Virtuoso reads the Load1, Load2, ... LoadN lines from the [Plugins] section and attaches them according to their type.
<module path> is the
directory containing shared modules for use with Virtuoso. (e.g.
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.
<module name> is the
file name of the modules shared library or object. (e.g.
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
__http_handler_pl(..) 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.
The handler will call the __hosting_http_handler VSE with a special set of parameters to represent the HTTP environment correctly.
There's a VSE to call each of the hosting modules:
__hosting_http_handler ( in
extension varchar, in
content varchar, [in
params varchar, ] [in
lines any, ] [inout
filename_head_ret varchar, ] [in
options any, ] [out
diag_ret varchar]) returns
Selects plugin by supported extension handler. e.g. pass 'pl' for the perl plugin.
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.
(optional) A string containing the HTTP parameters as encoded in the HTTP request body.
(optional) A vector (array) containing the HTTP request headers, in the same format as those passed to VSPs.
(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.
(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.
There is a "
__VIRT_CGI" = "
1" option to control whether the plugin operates in HTTP mode (
__VIRT_CGI=1) i.e. implements the CGI interface and treats the output as an HTTP response.
(optional) Returns various diagnostics messages returned while the code is running if any. The perl plugin sets this to the collected STDERR messages.
The function will return a varchar containing the HTTP body if
in HTTP mode (
__VIRT_CGI = 1 )
or the messages printed to STDOUT.
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:
[HTTPServer] PersistentHostingModules = 1/0 default 0
PersistentHostingModules to "1" prevents
Virtuoso from removing the interpreters from the HTTP threads after
The hosting_perl hosting module uses the perl