<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  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
 -  
 -  
-->

<sect1 id="createassembly"><title>CREATE ASSEMBLY Syntax - External Libraries</title>

<para>External CLR libraries can be hosted inside Virtuoso by creating an assembly
from the library itself using the syntax as follows:</para>

<programlisting><![CDATA[
CREATE ASSEMBLY <assembly_name> FROM <assembly_location>
  [WITH PERMISSION_SET = <perm>] [WITH AUTOREGISTER];
]]></programlisting>

<simplelist>
 <member><emphasis>assembly_name</emphasis> - is how Virtuoso will reference the library.</member>
 <member><emphasis>assembly_location</emphasis> - is where Virtuoso will find the library within the CLR.</member>
</simplelist>

<para>Every .NET assembly deployed inside Virtuoso will be verifiable, which
means it will contain code the CLR can verify to be safe in the way it writes
to memory. </para>

<para>Virtuoso also respects the Common Language Runtime's code access
security model. By default, code does not have any permissions to create a
graphical user interface, create threads, access the file system, or call
unmanaged code. The only permissions implemented are those granted for
in-process data access.</para>

<para>Administrators will control the permissions granted to assemblies using a
standard .NET machine and user-level security policy. At runtime, any code
accessing protected resources produces a stack walk that triggers a permissions
check against that code and any code that called it.</para>

<para>To simplify security administration, Virtuoso supports these standard
permission sets for .NET assemblies:</para>

<simplelist>
 <member><emphasis>SAFE</emphasis> - This is the default permission set.
 It allows internal computation and data access.  There is no access to resources outside
 of Virtuoso.  Calls to unmanaged code are not allowed. Code must be verifiable.</member>
 <!-- member><emphasis>EXTERNAL_ACCESS</emphasis> - The caller has to have these
 added permissions to create tables, assemblies, or other objects. </member -->
 <member><emphasis>UNRESTRICTED</emphasis> - Code can access any resource.
 Only system administrators (dba group/role) can run unrestricted code. This level allows
 calls to unmanaged code, and can be unverifiable.</member>
</simplelist>

<para>The restricted assemblies (SAFE mode) are not permitted to execute
any code that infringes upon any of the following permissions:</para>

<simplelist>
  <member>AspNetHostingPermission</member>
  <member>EnvironmentPermission </member>
  <member>FileIOPermission</member>
  <member>IsolatedStoragePermission</member>
  <member>ReflectionPermission</member>
  <member>RegistryPermission</member>
  <member>SecurityPermission</member>
  <member>SocketPermission</member>
  <member>WebPermissionPermission</member>
  <member>DNSPermission</member>
  <member>PrintingPermission</member>
  <member>OleDBPermissionPermission</member>
  <member>SqlClientPermissionPermission</member>
  <member>EventLogPermission</member>
  <member>MessageQueuePermission</member>
  <member>ServiceControllerPermission</member>
  <member>PerformanceCountersPermission  </member>
  <member>DirectoryServicePermission</member>
</simplelist>

<para>If the assembly generates a security exception the error text
will be returned to the client.</para>

<note><title>Note:</title>
  <para>Currently on the Microsoft .Net Framework implementation supports
  permission sets.  Virtuoso does not currently support the
  <computeroutput>EXTERNAL_ACCESS</computeroutput> permission set.</para></note>

<para><emphasis>WITH AUTOREGISTER</emphasis> marks the assembly as a stored
procedure, trigger, user-defined function, etc., based on custom attributes you add
to your .NET code.</para>

<para>Assemblies are stored in the database and  are therefore backed-up
and restored with the data.  Once assemblies are registered using the
<computeroutput>CREATE ASSEMBLY</computeroutput> syntax there will be no
further dependency on the library file (dll or exe) itself. </para>

<para>You can remove assemblies using the familiar SQL DROP statement: </para>

<programlisting><![CDATA[
DROP ASSEMBLY <assembly_name>;
]]></programlisting>

<tip><title>See Also:</title>
  <para><link linkend="fn_import_clr">import_clr()</link></para></tip>

<example id="ex_createassembly"><title>Working with assemblies</title>
<para>This example is based on the tutorial HO_S_10.  we start by obtaining a C#
library compile from the following code (included in the tutorial):</para>
<programlisting><![CDATA[
using System;

[Serializable]
public class Point_10
{
  public Double x;
  public Double y;

  public Point_10 ()
    {
      x = 0;
      y = 0;
    }
  public Point_10 (Double new_x, Double new_y)
    {
      x = new_x;
      y = new_y;
    }

  public Double distance (Point_10 p)
    {
      Double ret;

      ret =  Math.Sqrt ((p.x - this.x) * (p.x - this.x) + (p.y - this.y) * (p.y - this.y));

      return ret;
    }
}
]]></programlisting>

<para>This gives us the Point_10 class with two constructors and one method
for finding the distance between two points.</para>
<para>Now we must create the library reference in Virtuoso using the following:</para>

<programlisting><![CDATA[
DROP ASSEMBLY "myPoint";

CREATE ASSEMBLY "myPoint" as concat (http_root() , '\\tutorial\\hosting\\ho_s_10\\Point_ho_s_10.dll')
  WITH PERMISSION_SET = SAFE WITH AUTOREGISTER;
]]></programlisting>

<para>Now for a quick test, we will find the distance between two points:</para>

<programlisting><![CDATA[
SQL> select new Point_10(0,0).distance(Point_10(3,4));
callret
DOUBLE PRECISION
_______________________________________________________

               5
]]></programlisting>

<para>Now we will create a table with a column of type Point_10 and then insert
some test data:</para>

<programlisting><![CDATA[
drop table CLR..Supplier_ho_s_10;

create table CLR..Supplier_ho_s_10 (id integer primary key, name varchar (20), location Point_10);

insert into CLR..Supplier_ho_s_10 (id, name, location) values (1, 'S1', new Point_10 (1, 1));
insert into CLR..Supplier_ho_s_10 (id, name, location) values (2, 'S2', new Point_10 (3, 3));
insert into CLR..Supplier_ho_s_10 (id, name, location) values (3, 'S3', new Point_10 (5, 5));
]]></programlisting>

<para>Now we will demonstrate how this assembly's class can be used in SQL by
showing some queries on the sample data:</para>

<programlisting><![CDATA[
SQL> select name, s.location.x from CLR..Supplier_ho_s_10 s;
name                  callret
VARCHAR               DOUBLE PRECISION
_______________________________________________________________________________

S1                                   1
S2                                   3
S3                                   5
]]></programlisting>

<para>The distances from (0, 0):</para>

<programlisting><![CDATA[
SQL> select name, s.location.distance(Point_10(0,0)) from CLR..Supplier_ho_s_10 s ;
name                  callret
VARCHAR               DOUBLE PRECISION
_______________________________________________________________________________

S1                    1.414213562373095
S2                    4.242640687119285
S3                    7.071067811865476
]]></programlisting>

<para>Now, the points that are more than 3 units away from it:</para>

<programlisting><![CDATA[
SQL> select name from CLR..Supplier_ho_s_10 s where s.location.distance(Point_10(0,0)) > 3;
name
VARCHAR
_______________________________________________________________________________

S2
S3
]]></programlisting>
</example>


<example id="ex_createassembly2"><title>Using CREATE ASSEMBLY</title>
<para>This example demonstrates the creation of trivial CLR
classes and referencing them from Virtuoso.</para>

<itemizedlist>
 <listitem><emphasis>lib.cs</emphasis>
<programlisting><![CDATA[
namespace lib
{
  public class t1
  {
     public static int addit (int a1, int a2) { return a1 + a2; }
  }
}
]]></programlisting>
</listitem>

<listitem><emphasis>exe.cs</emphasis>
<programlisting><![CDATA[
using lib;

public class exe
{
   public static int call_addit (int a1, int a2)
   {
      return t1.addit (a1, a2);
   }

   public static void Main (String [] args)
   {
      Console.WriteLine ("result=" + call_addit (12, 13));
   }
}
]]></programlisting>
</listitem>

<listitem><emphasis>compilation</emphasis>
<programlisting><![CDATA[
csc /t:library lib.cs
csc /r:lib.dll exe.cs
]]></programlisting>
</listitem>

<listitem><emphasis>Now Virtuoso can use</emphasis>
<programlisting><![CDATA[
create assembly sql_lib from 'c:\sample\lib.dll'
create assembly sql_exe from 'c:\sample\exe.exe'
]]></programlisting>
</listitem>
</itemizedlist>
</example>

<example id="ex_ctasspermset"><title>Creating Assemblies with Permission Sets</title>

<para>These examples will use an assembly called test.dll, whose source code is:</para>

<programlisting><![CDATA[
using System;
using System.IO;

public class Sample
{
   public static String GetEnv ()
     {
       return Environment.GetEnvironmentVariable("PATH");
     }
}
]]></programlisting>

<para>The assembly will be registered using:</para>

<programlisting><![CDATA[
CREATE ASSEMBLY "test" from 'test.dll' WITH PERMISSION_SET = SAFE WITH AUTOREGISTER;
]]></programlisting>

<para>and subsequently called using:</para>

<programlisting><![CDATA[
SQL> select Sample::GetEnv ();
]]></programlisting>

<para>returning the following error for attempting to exceed the SAFE permission set.</para>

<programlisting><![CDATA[
*** Error 42000: [Virtuoso Driver][Virtuoso Server]CLR05: Request for the permission of type System.Security.Permissions.EnvironmentPermission,
      mscorlib, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 failed.
in
__udt_method_call:(BIF),
<Top Level>
at line 4 of Top-Level:
select Sample::GetEnv ()
]]></programlisting>

<para>Now we can try the same sample using PERMISSION_SET = UNRESTRICTED.</para>

<programlisting><![CDATA[
drop ASSEMBLY "test";

CREATE ASSEMBLY "test" from 'test.dll' WITH PERMISSION_SET = UNRESTRICTED WITH AUTOREGISTER;

SQL> select Sample::GetEnv ();
callret
VARCHAR
_______________________________________________________________________________

D:\Virtuoso\bin...;

1 Rows. -- 32 msec.
<]]></programlisting>

<para>Unrestricted assemblies do not have any restrictions on usage.</para>
</example>

</sect1>