<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry id="HO-S-2">
  <refmeta>
    <refentrytitle>ECMA-CLI(Mono)/.Net CLR Runtime Hosting</refentrytitle>
    <refmiscinfo>tutorial</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>Integrating Common Language Runtime Objects with Virtuoso</refname>
    <refpurpose>Using C# Objects to extend Virtuoso via User Defined Types.</refpurpose>
  </refnamediv>

    <refsect1 id="HO-S-2a_overview">
    <title>Overview</title>
    <para>The following tutorial demonstrates how Virtuoso can be extended 
    through the use of a .NET bound language such as C# to create User Defined 
    Types (UDTs), Stored Procedures, and Functions. This is an enhancement of its 
    Object-Relational Database functionality. </para>
    <para>The demonstrations in this section highlight transparent integration 
    (hosting) between Virtuoso and the Microsoft .NET and Mono implementations of 
    the ECMA Common Language Infrastructure (CLI). </para>
    </refsect1>
 
    <refsect1 id="HO-S-2a_prerequisites">
    <title>Prerequisites</title>
    <para>The following prerequisites ensure the usability of these  
    tutorial demos on Windows or Linux (and in other future Mono implementations): </para>
<itemizedlist>
 <listitem>Linux
   <itemizedlist>
     <listitem>Mono Runtime and Frameworks (ideally the version bundled with Virtuoso)</listitem>
     <listitem>Mono SDK (if you seek to write your own Objects for integration with Virtuoso)</listitem>
     <listitem>Virtuoso Universal Server for Linux with Mono Hosting</listitem>
     </itemizedlist></listitem>
<listitem>Windows
   <itemizedlist>
     <listitem>.NET Runtime and Frameworks</listitem>
     <listitem>.Net Runtime and Framework SDK (if you seek to write your own Objects for integration with Virtuoso)</listitem>
     <listitem>Virtuoso Universal Server for Windows with .NET CLR Hosting</listitem>
     </itemizedlist></listitem>
</itemizedlist>
    </refsect1>

    <refsect1 id="HO-S-2a">
    <title>Tutorial Example</title>

  <para>The following tutorial shows how C# classes are used to create User
  Defined Types (UDTs) in Virtuoso. </para>
  <para>Please follow the steps below to maximize the value of this tutorial:</para>

<orderedlist>
 <listitem>Click on the "Set Initial State" link which registers the two C# classes with Virtuoso. Click on the "ho_s_2.sql" link to see the code behind this step </listitem>
 <listitem>Click on the "Run" links to actually experience the demo</listitem>
</orderedlist>

<para>Demo Breakdown</para>

<orderedlist>
 <listitem>"ho_s_2.sql" performs the following steps
  <orderedlist>
   <listitem>Registers the "MyFinances" and "Point" classes with Virtuoso. Click 
   on the "MyFinances.cs" and "Point.cs" links to see the C# source code of these 
   classes</listitem>
   <listitem>Creates the conventional SQL table "Employee" </listitem>
   <listitem>Creates the Object-Relational table "Supplier" that includes a column 
   named "Location" that is of  Type "Point" (a UDT)</listitem>
   <listitem>Populates each of the newly created tables with data</listitem>
   <listitem>Creates the "distance" stored procedure which uses a C# function 
   member (method) to calculate the distance between points.</listitem>
  </orderedlist></listitem>

 <listitem>	"vsp1.vsp" uses the static method "tax" of the "MyFinances" class to 
 compute the payroll tax values for each employee via the "salary" column (like 
 a SQL function would). Take note of the Virtuoso class invocation syntax for 
 static C# methods (the relevant member function type in this demo; true to 
 C# these are called by name rather than instance).</listitem>
 <listitem>"vsp2.vsp" uses the "distance" method of the UDT based column 
 "location" to test for distance values less than "3". The distance values are 
 return values from the "Point" class. Note that the "Point" class computes 
 the distance between two arbitrary points.</listitem>
 <listitem>"vsp3.vsp" is a variation of the previous demo, with the column 
 "location" being used to access and conditionally test the values of data 
 member "x" (shown in "Point.cs" as 0).</listitem>
 <listitem>"vsp4.vsp" is another variation of a query on the "Supplier" table, 
 in this particular case the query uses a Stored Procedure (see definition in 
 "ho_s_2.sql") to filter its result set.  It achieves this by using data member 
 values "x" and "y" from column "location", and the arbitrary values 1 &amp; 
 2 as input parameters for the Stored Procedure "distance".  It then tests 
 the return values for those less than 3.</listitem>
</orderedlist>  
    </refsect1>
</refentry>
