File: installation.xml

package info (click to toggle)
virtuoso-opensource 7.2.5.1%2Bdfsg1-0.3
links: PTS, VCS
area: main
in suites: bookworm
size: 285,240 kB
sloc: ansic: 641,220; sql: 490,413; xml: 269,570; java: 83,893; javascript: 79,900; cpp: 36,927; sh: 31,653; cs: 25,702; php: 12,690; yacc: 10,227; lex: 7,601; makefile: 7,129; jsp: 4,523; awk: 1,697; perl: 1,013; ruby: 1,003; python: 326
file content (6767 lines) | stat: -rw-r--r-- 316,160 bytes
parent folder | download | duplicates (2)
<?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
 -  
 -  
-->
<chapter label="installation.xml" id="installation">
	<title>Installation Guide</title>
	<abstract>
		<para>This chapter applies exclusively to the various commercial releases of Virtuoso.  If you are working with the open source version, please refer to the instructions on the web site where you obtained it.  
</para>
		<para>
This chapter describes how to install OpenLink Virtuoso VDBMS.  It 
contains both a quick start install guide and full walk through install guides 
for major platforms.</para>
		<para>Virtuoso has been designed from the ground-up to be easy to implement.</para>
		<para>The installation generally runs without problems, run the setup program or script and follow
	the on screen instruction prompts.  You will be asked some questions, if in any doubt please follow
	the instructions in this guide in order to install and configure your Virtuoso components correctly. </para>
		<para>Once installed, each instance of Virtuoso is controlled by an
INI (initialization) file.  This file links the Virtuoso Server
process with an actual database file or device.  For example, the demo
instance of Virtuoso on all platforms is controlled by the demo.ini
file that is found in the demo directory along with the demo.db and
related files.  There is a one-to-one relationship between server
processes and database files.</para>
		<para>The INI file is a text file consisting of keys and key values.
You will set several of these values during installation.  At any time
thereafter, their values can be changed by editing the INI file with a
standard text editor.</para>

		<para>The details of the INI file sections, keys, and the meanings of
the key values are described in the <link
linkend="configsrvstupfiles">Configuring Server Startup Files</link>
section.
</para>

	</abstract>

	<sect1 id="installallplatforms">
		<title>Virtuoso on All platforms Commmon Specifics</title>
    <sect2 id="srvadminstallreqt"><title>Installation Requirements</title>
			<para>A typical installation will require a minimum of 400Mb of hard disk space to install the code, 
      samples, documentation and sample database. The database will need additional space for data inserted, 
      backups, logs and reports, web pages, etc.</para>
			<para>The size of the database .db file will not reduce when data is removed. The spare space will 
      however be reclaimed for later use.</para>
		</sect2>
    
    <sect2 id="srvadmopreq"><title>Operational Requirements</title>
			<para>The Virtuoso database requires a minimum of 64Mb of system memory for each instance to operate 
      in. Each connection will take between 70kb and 130kb of memory.</para>
			<para>The memory usage is affected by the following parameters in the
    <link linkend="VIRTINI">Virtuoso configuration file</link>.</para>
			<simplelist>
				<member>ServerThreads</member>
				<member>ServerThreadSize</member>
				<member>MainThreadSize</member>
				<member>FutureThreadSize</member>
				<member>NumberOfBuffers</member>
			</simplelist>
			<para>See the following <link linkend="parameters">Parameter section</link> for more details.</para>
		</sect2>
    
    <sect2 id="srvadmossupport"><title>Operating System Support</title>
			<para>Virtuoso runs on the following operating systems:</para>
			<simplelist>
				<member>Windows</member>
				<member>Linux</member>
				<member>Unix: AIX, HP-UX, Solaris, etc.</member>
				<member>Mac OS X</member>
			</simplelist>
		</sect2>
    
		<sect2 id="limitsandparameters">
			<title>Limits</title>
			<para>The below table lists the most important parameters and limits for a database or a Virtuoso 
      server instance. For space consumption of individual data types, see 
      <link linkend="SpaceConsump">Space Consumption</link>.</para>
			<table colsep="1" frame="all" rowsep="0" shortentry="0" tocentry="1" tabstyle="decimalstyle" orient="land" pgwide="0">
				<title>Limits</title>
				<tgroup align="char" charoff="50" char="." cols="2">
					<colspec align="left" colnum="1" colsep="0" colwidth="20pc"/>
					<thead>
						<row>
							<entry>Limit Description</entry>
							<entry>Value</entry>
						</row>
					</thead>
					<tbody>
            <row><entry>Identifier length</entry><entry>100</entry></row>
            <row><entry>User name and password length</entry><entry>100</entry></row>
            <row><entry>SQLstmt and proc text</entry><entry>100K+</entry></row>
            <row><entry>varchar length</entry><entry>Constrained by max row length when stored into non-LOB column, 10MB inside procedure code.</entry></row>
            <row><entry>Numeric precision</entry><entry>Max 40 digits</entry></row>
            <row><entry>LOB column length</entry><entry>2GB</entry></row>
            <row><entry>row length</entry><entry>4086</entry></row>
            <row><entry>Columns per row</entry><entry>200</entry></row>
            <row><entry>Database size</entry><entry>32TB for data, 32TB for temp data </entry></row>
            <row><entry>Page size</entry><entry>8K</entry></row>
            <row><entry>File size</entry><entry>64 bit file offsets on supporting OS's</entry></row>
            <row><entry>Files per database</entry><entry>unlimited</entry></row>
            <row><entry>Table size</entry><entry>Up to database size </entry></row>
            <row><entry>Tables per database</entry><entry>64K keys, a table takes 1 key for primary key, 1 key per index and 1 key for each obsolete primary key layout  resulting from adding or dropping columns.</entry></row>
            <row><entry>Indexes per table</entry><entry>Unlimited, subject to global cap on keys.</entry></row>
            <row><entry>Row in sorting/distinct temp</entry><entry>4078b, as in tables </entry></row>
            <row><entry>Locks per transaction</entry><entry>Depends on memory, 16b per row lock, 60b per page with at least one row lock.</entry></row>
            <row><entry>Changes per transaction</entry><entry>Depends on memory, ini parameter allows cap on  rollback before image.</entry></row>
            <row><entry>Virtual memory></entry><entry>Depends on OS, 64 bit pointers on 64 bit platforms</entry></row>
            <row><entry>Threads</entry><entry>Depends on OS, ini files specifies cap for pool for SQL client and web server worker thread pools.</entry></row>
            <row><entry>Max connections</entry><entry>Depends on OS fdset size, at least 2048, license can set a limit</entry></row>
            <row><entry>Memory per connection</entry><entry>22K plus up to 100 cached SQL statement compilations</entry></row>
          </tbody>
       </tgroup>
      </table>
    </sect2>
  </sect1>
  
	<sect1 id="installwin32">
		<title>Virtuoso for Windows</title>
		<sect2 id="b4ustart">
			<title>Before You Start</title>
			<para>To ensure a smooth installation, please review the
    following checklist before you start the setup program.</para>
			<sect3 id="haveudld">
				<title>Have you downloaded the software?</title>
				<para>If you have not already done so, please download your copy of OpenLink
    Virtuoso from the OpenLink web site.  The URL is
    <ulink url="http://www.openlinksw.com">http://www.openlinksw.com</ulink>.
    When you visit the site, select &quot;Download &amp; Evaluation&quot;. </para>
                                <orderedlist>
                                   <listitem>
                                     <para>Select product &quot;OpenLink Virtuoso: Personal Edition &quot;</para>
                                   </listitem>
                                   <listitem>
                                     <para>From &quot;Product Category&quot; choose &quot;Universal Server&quot;</para>
                                   </listitem>
                                   <listitem>
                                     <para>From &quot;Product&quot; choose &quot;Virtuoso Universal Server&quot;</para>
                                   </listitem>
                                   <listitem>
                                     <para>Select &quot;Database Version&quot;</para>
                                   </listitem>
                                   <listitem>
                                     <para>From &quot;server OS&quot; select &quot;Windows&quot; and click &quot;Next&quot;</para>
                                   </listitem>
                                   <listitem>
                                     <para>Select a release and click &quot;Next&quot;</para>
                                   </listitem>
                                   <listitem>
                                     <para>You will be prompt to login in not already.</para>
                                   </listitem>
                                   <listitem>
                                     <para>Click &quot;Next&quot;</para>
                                   </listitem>
                                   <listitem>
                                     <para>Download the desired component. For example, click the HTTP link for &quot;Multi-Threaded Universal Server (Commercial Edition)  for OpenLink Virtuoso 4.x&quot;</para>
                                   </listitem>
                                </orderedlist>
			</sect3>
			<sect3 id="douhavelic">
				<title>Do you have the License file?</title>
				<para>The server will need a license file, and this is automatically delivered by email
				as part of the download process. It is therefore important to supply a valid email
				address. The installer will prompt for the license file location.</para>
			</sect3>

			<sect3 id="reinstvirt">
				<title>Reinstalling Virtuoso?</title>
				<para>If you are reinstalling Virtuoso, you must first shutdown any
    additional database servers you have configured on non default ports.
    The databases on port 1111 and 1112 will automatically be stopped during the install process.
    On Windows NT/2000/XP, go to the services applet in the Control Panel.  There
    you can stop services that appear with names of the form &quot;OpenLink
    Virtuoso DBMS Server [instance name]&quot;.</para>
				<para>On Windows NT/2000/XP you can also shut them down with the following
    commands in the Virtuoso\bin directory:</para>
			<programlisting>
virtuoso-odbc-t.exe +service stop
virtuoso-odbc-t.exe +instance myinstance +service stop
virtuoso-odbc-t.exe +instance anotherinstance +service stop
</programlisting>

<note><title>Note:</title>
<para>There is an alternative executable available for Virtuoso
called: virtuoso-odbc-f.exe, which you may have installed.  This version is
designed for versions of Windows that offer no native threading support
such as Windows 98, and offers no advantages over virtuoso-odbc-t.exe
for Windows NT/2000/XP.</para></note>

				<para>You can list the services with their status using:</para>
				<programlisting>virtuoso +service list</programlisting>
			</sect3>
			<sect3 id="allocoftcpports">
				<title>Allocation of TCP/IP ports</title>
				<para>The Default database have the following port allocations:</para>
<table><title>Port Usage</title>
  <tgroup cols="2">
 <thead><row><entry>Port</entry><entry>Used by</entry></row></thead>
 <tbody>
						<row>
  <entry>1111</entry>
  <entry>Default Virtuoso Server port</entry></row>
						<row>
  <entry>8889</entry>
  <entry>Default Virtuoso Visual Server Administration Interface HTTP port</entry></row>
					</tbody>
				</tgroup>
			</table>
				<para>By default, the Virtuoso DBMS listens on port 1111.
    This port number is not selectable at install time.
    If the port is currently in use by another server then after the installation completes
    you will need to change the port number in the Local Virtuoso ODBC DSN that is created
    during the installation process, and also in the following file:</para>
				<programlisting>
C:\Program Files\OpenLink Software\Virtuoso 5.0\bin\virtuoso.ini
</programlisting>
				<para>To check if a port is in use on NT, you can use the
    following command, and review the output:</para>
				<programlisting>
netstat -an | more
</programlisting>
			</sect3>
			<sect3 id="prevworkodbcdsn">
				<title>Do you already have an ODBC Data Source Name (DSN) that works?</title>
				<para>The Virtual Database aspects of the Virtuoso for ODBC assumes that you already
	have an ODBC driver on your machine from a database vendor, OpenLink Software, or from another 3rd party vendor.
	It is a useful sanity-check to ensure that you have an ODBC System Data Source Name (DSN) on your
    machine, and that it successfully connects to your database, and that it retrieve
    data.  Any ODBC compliant tool can be used to test that your ODBC Data Source Name
    (DSN) works, such as the sample application we provide - C++ Demo32, and that it is
    sufficiently robust to operate with Virtuoso. Virtuoso is ODBC Driver Independent and
    certified to work with any drivers that are ODBC level 1 or higher.</para>
			</sect3>
		</sect2>
		<sect2 id="knowthywinvirt">
			<title>Getting To Know Your Virtuoso Components</title>
			<para>Virtuoso is made up of several components, these components
    fall into two distinct categories: Client Components and Server Components.</para>
			<sect3 id="clicomppack">
				<title>Client Components Package</title>
				<para>These are the components typically used to communicate with
    a local or remote Virtuoso server, this includes: </para>
				<simplelist>
					<member>Virtuoso Drivers for ODBC</member>
					<member>Virtuoso Drivers for JDBC</member>
					<member>ISQL Utility</member>
					<member>ISQLO Utility</member>
					<member>Documentation</member>
					<member>Samples</member>
				</simplelist>
			</sect3>
			<sect3 id="srvcomp">
				<title>Server Components</title>
				<para>These are the components that service Virtuoso clients,
				    these include:</para>
				<simplelist>
					<member>
					Virtuoso Virtual Database Servers for: ODBC based
					interfaces - the files &quot;virtuoso-odbc-f&quot; (for Virtuoso Lite)
				        and &quot;virtuoso-odbc-t&quot; (For Virtuoso Enterprise Edition).
					</member>
					<member>Virtuoso HTTP Server.
					</member>
					<member>Virtuoso System Manager to configure the database
					through the HTTP interface.
					</member>
				</simplelist>
			</sect3>
		</sect2>
		<sect2 id="InstallStepsWin">
			<title>Installation Steps</title>
		  <sect3 id="InstallStepsWinPrepareToInstall">
		    <title>Prepare to Install</title>
		    <para>If you are upgrading an existing Virtuoso installation and want to preserve your existing data and configuration files:</para>
        <orderedlist>
          <listitem>Shut down your Virtuoso instance as normal.</listitem>
          <listitem>Right-click on the existing <code>Virtuoso.app</code> (exact name may vary), and select
          <code>Show Package Contents</code>.</listitem>
          <listitem>Drill down to <code>Contents</code> -&lt; <code>virtuoso</code> -&lt; <code>database</code>.</listitem>
          <listitem>Check the size of the <code>virtuoso.trx</code> file, found in the <code>database</code> folder alongside the
          <code>virtuoso.db</code> and <code>virtuoso.ini</code> files.
            <itemizedlist mark="bullet">
              <listitem>If zero bytes, proceed to step 6.</listitem>
              <listitem>If larger than zero bytes, start the instance from the command line with the extra argument,
              "<link linkend="COMMANDLINE">+checkpoint-only</link>", and recheck <code>.trx</code> file size -- expecting
              zero bytes.</listitem>
              <listitem>If larger <code>.trx</code> files persist,
              <ulink url="http://support.openlinksw.com/support/online-support.vsp">contact Technical Support</ulink>.</listitem>
            </itemizedlist>
					</listitem>
          <listitem>Make a backup of your existing Virtuoso Database and Configuration files (defaults are <code>virtuoso.db</code> and
          <code>virtuoso.ini</code>) prior to performing the steps that follow. <i><emphasis>Note</emphasis>: Virtuoso's
          <link linkend="onlinebackups">online backup feature</link>, if enabled, should have already generated a backup-set</i>.</listitem>
          <listitem> Use the Add/Remove Programs utility to uninstall any previously installed Virtuoso components. Data and
          configuration files will be left behind by this process.</listitem>
        </orderedlist>
		  </sect3>
		  <sect3 id="InstallStepsWinDownload">
		    <title>Download the Virtuoso Installer Program</title>
        <orderedlist>
          <listitem>Download the <ulink url="http://opldownload.s3.amazonaws.com/uda%2Fvirtuoso%2F7.2%2Fx86_64-generic-win-64%2Fwavpz2zz.msi#this">Virtuoso 7.2 installer archive (wavpz2zz.msi)</ulink>
          from the <ulink url="http://virtuoso.openlinksw.com/download/">download site</ulink>. <i><emphasis>Note</emphasis>: Virtuoso
          7.x is 64-bit only, and requires Vista or Windows Server 2003, or later.</i></listitem>
        </orderedlist>
		  </sect3>
		  <sect3 id="InstallStepsWinObtainLicense">
		    <title>Obtain a License File</title>
        <orderedlist>
          <listitem> If you haven't already obtained a suitable Virtuoso 7.x license file, return to the
          <ulink url="http://virtuoso.openlinksw.com/download/">download site</ulink>, and click the link for
          <emphasis>Free Eval License</emphasis> (15 day duration, requires only your email address) or
          <emphasis>Free Pilot License</emphasis> (30 day duration, requires some additional personal and business information).
            <figure id="wininstobtainlic" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Obtain a License File</title>
              <graphic fileref="ui/win_obtain_license.jpg"/>
						</figure>
					</listitem>
          <listitem>Fill out the relevant form, and download the license file when presented. <i><emphasis>Note</emphasis>: the
          file must be named <code>virtuoso.lic</code> for use. Some browsers may rename the file during download; you can simply
          rename the file on your machine.</i>
					</listitem>
        </orderedlist>
		  </sect3>
		  <sect3 id="InstallStepsWinRunInstaller">
		    <title>Run the Virtuoso Installer</title>
		    <para></para>
        <orderedlist>
          <listitem>Double-click the installer archive, <code>wavpz2zz.msi</code>, to start the process with the Installer Program
          Introduction.
            <figure id="wininstruninst" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Run the Virtuoso Installer</title>
              <graphic fileref="ui/win_installer_program.jpg"/>
						</figure>
					</listitem>
          <listitem>Click <emphasis>Next</emphasis>, and you'll be presented with the License Agreement:
            <figure id="wininstrunnext" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- License Agreement</title>
              <graphic fileref="ui/win_license_agreement.jpg"/>
						</figure>
					</listitem>
          <listitem>Tick the box for <emphasis>I accept</emphasis>, and click <emphasis>Next</emphasis>. You'll be asked to locate
          your license file:
            <figure id="wininstrunnextaccept" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- License Agreement Accept</title>
              <graphic fileref="ui/win_install_folder.jpg"/>
						</figure>
					</listitem>
          <listitem>Use the <emphasis>Browse</emphasis> button to locate the license file you obtained earlier, or click the
          <emphasis>Try and Buy</emphasis> button to obtain a new one now, or tick the box for
          <emphasis>I don't want to install a license file now</emphasis>. Then, click <emphasis>Next</emphasis>. You'll be
          prompted to select an Installation Type:
            <figure id="wininstrunnextbrowse" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Choose Installation Type</title>
              <graphic fileref="ui/win_install_type.jpg"/>
						</figure>
					</listitem>
          <listitem> Select the desired option:
            <itemizedlist mark="bullet">
              <listitem><emphasis>Typical</emphasis> -- installs to the default filesystem location, may not include all components</listitem>
              <listitem><emphasis>Complete</emphasis> -- installs to the default filesystem location, includes all components</listitem>
              <listitem><emphasis>Custom</emphasis> -- to install to any filesystem location, and select which components will be installed</listitem>
            </itemizedlist>
                                        </listitem>
          <listitem>Click <emphasis>Next</emphasis>, and if you chose <emphasis>Typical</emphasis> or <emphasis>Complete</emphasis>,
          skip this and the next step; if you chose <emphasis></emphasis>Custom, you'll be prompted to choose a destination folder:
            <figure id="wininstrunnextfolder" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Choose Destination Folder</title>
              <graphic fileref="ui/win_destination_folder.jpg"/>
                                          </figure>
                                        </listitem>
          <listitem>Click <emphasis>Next</emphasis>, and if you chose <emphasis>Custom</emphasis>, you'll be prompted for Feature Selection:
            <figure id="wininstrunnextfeature" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Feature Selection</title>
              <graphic fileref="ui/win_feature_selection.jpg."/>
                                          </figure>
                                        </listitem>
          <listitem>Click <emphasis>Next</emphasis>, and the installer will indicate it's ready to begin:
            <figure id="wininstrunnextready" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Read to install</title>
              <graphic fileref="ui/win_file_copystart.jpg"/>
                                            </figure>
                                          </listitem>
          <listitem>Click install, and wait for notification of completion.</listitem>
                                        </orderedlist>
			</sect3>
		  <sect3 id="InstallStepsWinStartService">
		    <title>Start the Virtuoso Service Manager, and Locate it in the Task Bar</title>
				<orderedlist>
          <listitem>Launch the Virtuoso Service Manager from your <emphasis>Start</emphasis> menu.
            <figure id="winstartservlaunch" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Launch the Virtuoso Service Manager.</title>
              <graphic fileref="ui/win_locate_manager.jpg"/>
						</figure>
					</listitem>
          <listitem>Look for an icon to appear in the Task Bar at the bottom right of your screen.
            <figure id="winstartservicon" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Look for an icon</title>
              <graphic fileref="win_launch_manager.jpg"/>
						</figure>
					</listitem>
				</orderedlist>
			</sect3>
		  <sect3 id="InstallStepsWinAdminInst">
		    <title>Start and Administer your Virtuoso Instance</title>
					<orderedlist>
          <listitem>Right-click on the Virtuoso Service Manager icon in the Task Bar, and click on
          <emphasis>OpenLink Virtuoso Server - Start</emphasis>:
            <figure id="winstartadminstart" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Start your Virtuoso Instance</title>
              <graphic fileref="win_start_service.jpg"/>
							</figure>
						</listitem>
          <listitem>Open the <emphasis>Virtuoso Conductor</emphasis>, Virtuoso's HTTP-based administration tool, by loading this URL in
          your Web Browser: <ulink url="http://example.com/conductor">http://example.com/conductor</ulink> .
            <figure id="winstartadmincond" float="1">
              <title>Installing the Virtuoso Universal Server on Windows -- Virtuoso Conductor</title>
              <graphic fileref="win_virt_admin.jpg"/>
            </figure>
						</listitem>
          <listitem>Use the Conductor to configure your Virtuoso instance for future use. For example, it is
          <i><emphasis>strongly</emphasis></i> advised that you change the default passwords for the <emphasis>dba</emphasis> and
          <emphasis>dav</emphasis> super-user accounts (drill down to <emphasis>System Admin</emphasis> -&lt; <emphasis>User
          Accounts</emphasis>).</listitem>
					</orderedlist>
		  </sect3>
		  <sect3 id="InstallStepsWinOptional">
		    <title>Optional - Restore your old Data and Configuration Files</title>
		    <para>If you preserved existing data and configuration files at the start of this process, now is the time to bring them back into play.</para>
					<orderedlist>
          <listitem>If you used Virtuoso's online backup feature, <link linkend="onlinebackups">the documentation</link> will walk you through the restoration process.</listitem>
          <listitem>If you simply copied the INI and DB files elsewhere, and if they were Virtuoso 7.x files, you can just stop the current Virtuoso instance, and replace the newly created INI and DB with the old ones. For best results, we do advise that you compare the content of the old INI with the new, and add any new settings from the new to the old, adjust as may be appropriate to your deployment.</listitem>
          <listitem>If you simply copied the INI and DB files elsewhere, and if they were Virtuoso 6.x or older files, there are some extra steps that must be taken.</listitem>
					</orderedlist>
			</sect3>
		</sect2>
		
		<sect2 id="wininstpost"><title>Post Installation</title>  
  <sect3 id="wininstpostsan">
			<title>Post-Installation Sanity Check</title>
			<para>A quick way to check that the database is running, is to point a browser to the
			http port. The following example URLs will show the System Manager for
			the default, and the demo Virtuoso databases:</para>
			<programlisting>
http://example.com
http://example.com:8890
</programlisting>
		</sect3>
		<sect3 id="wininstposttrb"><title>Troubleshooting DB Startup Failures</title>  
  <para><emphasis>Install failure</emphasis></para> 
  <para>Check the .log file in your Virtuoso installation db location, for ex:</para>
<programlisting><![CDATA[
	C:\Program Files\OpenLink Software\Virtuoso 7.2\db\virtuoso.log
]]></programlisting>  
<para>which is for the database and log files etc. in order to review the installed files 
binaries and databases (defaults) for issues if install fails.</para>
   <para><emphasis>.lck existance</emphasis></para>   
   <para>Check .log in case of .lck issue</para>
   <para>Delete the .lck file and repeat the steps from above.</para>
   <para><emphasis>.trx incompatiblity issue</emphasis></para>   
   <para>Check .log in case of .trx incompatiblity issue</para>
   <para><emphasis>oplmgr issue</emphasis></para>     
   <para>See <link linkend="oplmngrdlptl">Troubleshooting License Problems</link></para> 
  </sect3> 
  </sect2>
  
		<sect2 id="startvdbms">
			<title>Starting Your Virtuoso Server</title>
			<para>Due to subtle differences between the Windows 95 family (including Windows 98 and Windows ME) 
				and the Windows NT family (including Windows 2000, Windows XP, Vista, Windows 7, Windows 2000 
				Server, Windows Server 2003, and Windows Server 2008), specific instructions for starting and 
				stopping your Virtuoso server are supplied for each Windows family.</para>
			<sect3 id="winnt">
				<title>Windows NT family</title>
				<para>You can start your Virtuoso server in one of two ways,
    automatically or manually, the default mode configured by your installer is Automatic.</para>
				<sect4 id="winntautostart">
					<title>Automatic Startup</title>
					<para>Your Virtuoso servers (default and demonstration databases)
    are configured at installation time as &quot;Automatic Startup&quot; services. Thus,
    rebooting your machine after installation is all that is required in order for your
    Virtuoso servers to be ready to start receiving connections from client applications.
    The service is actually started during the installation, however some files may be locked, so
    a reboot is required to complete the install.</para>
				</sect4>
				<sect4 id="winntmanstart">
					<title>Manual Startup</title>
					<para>You can manually start your Virtuoso server in one of two
    ways, either via the &quot;services&quot; control panel applet or from within a DOS shell.
    When doing this via the &quot;Services&quot; control panel Applet you need to simply open
    up your control panel and click on the &quot;services&quot; applet. This will present you
    with a screen similar to the one below:</para>
					<figure id="inst016" float="1">
						<title>Services Applet</title>
						<graphic fileref="virtinst12.gif" width="505" depth="277"/>
					</figure>
					<para>Click the &quot;Start&quot; or &quot;Stop&quot; button in
    order to start or stop a highlighted Virtuoso Server.</para>
					<para>To start your Virtuoso servers manually using DOS command
    prompts, start a DOS shell and then enter the following command:</para>
					<programlisting>virtuoso-odbc-f +service start</programlisting>
				</sect4>
			</sect3>
			<sect3 id="win9x">
				<title>Windows 95 family</title>
				<para>You can start your Virtuoso server under Windows 95/98 in
    one of two ways, automatically or manually, the default mode configured by your installer
    is Automatic.</para>
				<sect4 id="win9xautostart">
					<title>Automatic Startup</title>
					<para>Your Virtuoso servers (default and demonstration databases)
    are configured at installation time as &quot;Automatic Startup&quot; services. Thus,
    rebooting your machine after installation is all that is required in order for your
    Virtuoso servers to be ready to start receiving connections from client applications.</para>
					<para>If Virtuoso does not start  automatically on Windows
    95/98 after installation you will need to add the following line to the system's
    &quot;autoexec.bat&quot; file (assuming you have installed Virtuoso using the installers
    default installation folder):</para>
					<programlisting>C:\Program Files\OpenLink\Virtuoso\bin\virtuoso-odbc-f +service start</programlisting>
				</sect4>
				<sect4 id="sect4win9xmanstart">
					<title>Manual Startup</title>
					<para>You can start your Virtuoso servers manually by
					entering the following commands at the DOS command line prompt:</para>
					<programlisting>
virtuoso-odbc-f +service start
virtuoso-odbc-f +instance demo +service start
</programlisting>
					<note>
						<title>Note:</title>
						<para>If you encounter a &quot;Program
    Not Found&quot; error this is because your Virtuoso installation&apos;s &quot;bin&quot;
    sub-directory is not part of your PATH environment variable. </para>
					</note>
				</sect4>
			</sect3>
		</sect2>
	
		<sect2 id="CreatingDeletingServices">
			<title>Creating and Deleting Virtuoso Services </title>
			<para>At sometime you may need to have multiple Virtuoso server
    processes running on your Windows servers or simply need to add or delete existing
    Virtuoso servers that have been registered with the &quot;Services&quot; control panel
    applet. You do this by executing the following commands:</para>
			<para>Adding new Virtuoso Server service: virtuoso-odbc-f +service create -I &lt;your chosen service name&gt;</para>
			<para>Deleting an existing Virtuoso service: virtuoso-odbc-f +service delete -I &lt;service that you are deleting&gt;</para>
			<para>Starting a new Virtuoso service manually: virtuoso-odbc-f +service start -I &lt;service name&gt; </para>
			<para>Showing a list of existing Virtuoso services: virtuoso-odbc-f +service list</para>
			<note>
				<title>Note:</title>
				<para>This functionality is only available on Windows NT/2000/XP.</para>
        <para>Ensure that the services applet from the control panel is closed while
        issuing the above commands to prevent locking.</para>
			</note>
		</sect2>
		<sect2 id="ConfiguringVirtuosoClients">
			<title>Configuring Virtuoso Client Components</title>
			<para>The Virtuoso client components set consists of the following:</para>

      <simplelist>
				<member>Virtuoso Driver for ODBC</member>
				<member>Virtuoso Driver for JDBC</member>
				<member>Native Virtuoso Interactive SQL Query (ISQL)</member>
				<member>ODBC based Interactive SQL Query Utility (ISQLO)</member>
			</simplelist>

      <para>The sections that follow address the configuration and
    utilization of each one of these client components separately.</para>
			<sect3 id="VirtuosoDriverODBC">
				<title>Virtuoso Driver for ODBC</title>
				<para>The Virtuoso Driver for ODBC conforms to both the ODBC
    1.x,2.x,and 3.x versions of the ODBC specification, it implements Core, Level 1, Level 2,
    and Extensions functionality. This driver enables you to communicate with local or remote
    Virtuoso servers across any combination of platforms supported by Virtuoso.</para>
				<para>At installation time two ODBC data source names (DSN&apos;s)
    are created with default values by the Virtuoso installer, the first DSN named &quot;Local
    Virtuoso&quot; provides a link to a local default Virtuoso database server instance, while
    the other named &quot;Local Virtuoso Demo&quot; provides a link to a local Virtuoso server
    for the Virtuoso demonstration database.</para>
    <tip><title>See Also:</title>
    <para>the <link linkend="virtdsnsetup">Data Access Interfaces</link> chapter for more detailed information
    regarding the Virtuoso ODBC Driver setup</para>
    </tip>
			</sect3>
			<sect3 id="VirtuosoDriverJDBC">
				<title>Virtuoso Drivers for JDBC</title>
				<para>The Virtuoso Drivers for JDBC are available in
    &quot;jar&quot; file formats for the JDBC 1.x, JDBC 2.x and JDBC 3.x JDBC specifications. These
    are Type 4 Drivers implying that utilization is simply a case of adding the relevant
    &quot;jar&quot; file to your CLASSPATH and then providing an appropriate JDBC URL format
    in order to establish a JDBC session with a local or remote Virtuoso server. It is
    important to note that when you make a JDBC connection to a Virtuoso Server, you do also
    have access to Native and External Virtuoso tables. Thus, you actually have a type 4 JDBC
    Driver for any number of different database types that have been linked into Virtuoso.</para>

    <tip><title>See Also:</title>
    <para>The <link linkend="VirtuosoDriverJDBC">JDBC Driver</link> section in
    the Access Interfaces chapter.</para></tip>

    </sect3>

			<sect3 id="ISQL">
				<title>Native Virtuoso Interactive SQL Query (ISQL)</title>
				<para>To assist you with the use of Virtuoso an
    interactive SQL interpreter utility called &quot;ISQL&quot; is bundled with all Virtuoso
    installations. This utility allows you to enter and execute SQL statements from a command
    line prompt against a local or remote Virtuoso server.</para>
				<para>The command line format for executing this utility is: </para>
				<programlisting>
isql [&lt;hostname&gt;][:&lt;port#&gt;]</programlisting>
				<para>The steps that follow guide you through the process of
    using ISQL to verify your Virtuoso installation:</para>
				<orderedlist>
					<listitem>
						<para>Open up a DOS shell</para>
					</listitem>
					<listitem>
						<para>Move into the &quot;bin&quot; sub-directory of your
        Virtuoso installation</para>
					</listitem>
					<listitem>
						<para>Type the following command: isql</para>
						<para>This will connect you to the default Virtuoso server at port &quot;1111&quot;, if you want
        to connect to your demonstration Virtuoso database (which listens at port 1112 by default)
        then enter: isql 1112</para>
					</listitem>
					<listitem>
						<para>At the ISQL command line prompt type in the following
        command: </para>
						<programlisting>
tables ;</programlisting>
						<para>This will produce a list of tables in the current Virtuoso database, you can also enter
        other SQL statements e.g.: </para>
						<programlisting>
select * from Customers</programlisting>
						<para>This will produce a listing of records in the &quot;Customers&quot; table.</para>
					</listitem>
					<listitem>
						<para>If you are not able to perform these task that it implies
        that your Virtuoso database server is not running or that it has not been installed
        properly.</para>
					</listitem>
				</orderedlist>
			</sect3>
			<sect3 id="ISQLO">
				<title>ODBC based Interactive SQL Query Utility (ISQLO)</title>
				<para>In addition to a Native ISQL utility, your Virtuoso
    installation includes an ODBC based version of &quot;ISQL&quot; called &quot;ISQLO&quot;,
    this enable you to connect to ODBC DSN&apos;s rather than Virtuoso only. To use this program
    perform the following steps: </para>
				<orderedlist>
					<listitem>
						<para>Open up a DOS shell</para>
					</listitem>
					<listitem>
						<para>Move into the &quot;bin&quot; sub-directory of your
        Virtuoso installation</para>
					</listitem>
					<listitem>
						<para>Type the following command :</para>
						<programlisting>
isqlo &lt;enter a valid ODBC Data Source Name&gt;</programlisting>
						<note>
							<title>Note:</title>
							<para>If your DSN contains spaces you will need to enclose it within
        double quotes when passing it as a parameter to ISQLO</para>
						</note>
					</listitem>
					<listitem>
						<para>Enter any valid SQL at the ISQLO command line prompt.</para>
					</listitem>
					<listitem>
						<para>You can also use this utility from within the Virtuoso Conductor</para>
					</listitem>
				</orderedlist>
			</sect3>
		</sect2>
		<sect2 id="defpasschgwin">
			<title>Default passwords</title>
			<para>See the following Quick Start chapter for very important information about
			<link linkend="defpasschange">changing the default passwords</link>.</para>
		</sect2>

	</sect1>
	<!-- obsolete
	<sect1 id="linuxinstall">
		<title>Virtuoso for Linux (Enterprise Edition)</title>
		<sect2 id="b4instlin">
			<title>Before You Install</title>
			<para>To ensure a smooth installation, please review the
      following checklist before you start the setup program.</para>
			<sect3 id="linhavudld">
				<title>Have you downloaded the software?</title>
				<para>If you have not already done so, please download your copy of OpenLink
      Virtuoso from the Virtuoso web site.  The URL is
		<ulink url="http://www.openlinksw.com/virtuoso/">http://www.openlinksw.com/virtuoso/</ulink>.
		When you visit the site, select &quot;Software Download&quot;.</para>
			</sect3>
			<sect3 id="linreinstvirt">
				<title>Reinstalling Virtuoso?</title>
				<para>If you are reinstalling Virtuoso, you must first stop
      the Database Servers. You can shut these services down with the following command
      executed from your Linux shell prompt:</para>
				<para>Beta 1 Users</para>
				<programlisting>sh virtuoso-lite.rc stop</programlisting>
				<para>or</para>
				<programlisting>virtuoso-lite.rc stop</programlisting>
				<para>or</para>
				<programlisting>./virtuoso-lite.rc stop</programlisting>
				<para>Beta 2 Users</para>
				<programlisting>sh virtuoso-stop.sh</programlisting>
				<para>or</para>
				<programlisting>virtuoso-stop.sh</programlisting>
				<para>or</para>
				<programlisting>./virtuoso-stop.sh</programlisting>
				<para>You may also want to first uninstall prior Virtuoso RPM packages.</para>
				<para>The following command (executed as root) can be used to uninstall the package:</para>
				<programlisting>rpm -e virtuoso-lite-1.1-3_glibc2</programlisting>
				<para>or</para>
				<programlisting>rpm -e virtuoso-enterprise-1.1-3_glibc2</programlisting>
				<para>or</para>
				<programlisting>rpm -e virtuoso-lite-1.1-3_libc5</programlisting>
				<para>depending on Linux system and Virtuoso Server being used.</para>
			</sect3>
			<sect3 id="linportsfree">
				<title>Are ports 1111,1112, 8889 and 8890 free?</title>
				<para>During the installation you will be prompted for an HTTP port number for
				use by each Virtuoso System Manager. If you are already running a web server
      or other listener on that port, you will encounter problems, and should choose another
      free port when you are prompted.  </para>
				<para>By default, the Virtuoso DBMS listens on port 1111, and the Demo Database
      on 1112. If these ports is currently in use by another server then after the installation completes,
      you will need to change the port numbers in the Local Virtuoso ODBC or UDBC DSN that is
      created during the installation process, and also in the following file:</para>
				<programlisting>$&lt;Directory where Virtuoso is installed&gt;/bin/virtuoso.ini</programlisting>
				<para>typically</para>
				<programlisting>/usr/local/virtuoso</programlisting>
				<para>but can of course be any location of your choosing.</para>
				<para>To check if a port is in use you can use the following command, and review the output:</para>
				<programlisting>netstat -an | more </programlisting>
			</sect3>
			<sect3 id="lindouvirtuser">
				<title>Do you already have a &quot;virtuoso&quot; user account on your Linux system?</title>
				<para>Although this is no longer a requirement of the installation it
may be suitable to create a new Virtuoso user account for administering the Virtuoso
server.</para>
			</sect3>
			<sect3 id="liniodbc">
				<title>Do you already have functional iODBC data sources on your system?</title>
				<para>The OpenLink Virtuoso for Linux installation presumes the following:</para>
				<simplelist>
					<member>You intend to connect to a Local Virtuoso server using iODBC
          or OpenLink  UDBC</member>
					<member>You intend to connect to one or more Remote Virtuoso servers
          on your network using iODBC or UDBC </member>
					<member>You intend to Attach tables hosted within non-local or
          Remote Virtuoso database servers, into a Local or Remote Virtuoso Server</member>
					<member>The existence of functional OpenLink or third-party iODBC
          drivers for Linux that connect to the non database servers referred to above.</member>
					<member>In the absence of iODBC drivers for your non Virtuoso
          database, that a functional OpenLink or third-party UDBC Drivers exists for these database
          servers. </member>
				</simplelist>
				<para>Instructions on how to manually configure iODBC Data Source
      Names is available at the following URL:
      <ulink url="http://www.openlinksw.com/info/docs/rel3doc/unix/odbcsdk.htm">http://www.openlinksw.com/info/docs/rel3doc/unix/odbcsdk.htm</ulink>
      If you are using OpenLink Multi-Tier ODBC
      Drivers for your remote database connections then we highly recommend the use of the Virtuoso
      System Manager for creating iODBC Data Source Names.</para>
			</sect3>
			<sect3 id="liniodbcdsnfunc">
				<title>Are your iODBC Data Source Names functional?</title>
				<para>It is a useful sanity-check to ensure that your iODBC or UDBC
      data sources are functional, OpenLink provides an &quot;odbctest&quot; program for
      verifying basic usability of iODBC data sources. Both of these programs reside in the
      &quot;samples&quot; directory situated beneath the directory into which RPM installs
      Virtuoso.</para>
			</sect3>
		</sect2>
		<sect2 id="instproclinux">
			<title>Installation Process</title>
			<para>Once you have downloaded the required tar file from the
web or ftp site and have placed the file in a designated installation directory you are
ready to commence the Virtuoso installation process. </para>
			<para>You may want to specify a new user to own the Virtuoso
installation and then you can place the installation tar file into that users home
directory.</para>
<orderedlist>
  <listitem><para>First step is to un-tar the file to obtain the install script
  and archive file.  Use the following command:</para>
  <programlisting>tar xvf &lt;tar file&gt;.tar</programlisting>
  <para>replacing &lt;tar file&gt; with the relevant name of the file you downloaded.</para></listitem>
  <listitem><para>run the install script using the following command:</para>
<programlisting>[virtuoso@myserver virtuoso]$ sh /install.sh</programlisting>
  <para>The installation process will now begin and prompt you for required information.</para>
</listitem>

<listitem>
<para>The install script will first try and detect running Virtuoso server instances.
In cases where an old Virtuoso server is being upgraded you must ensure that
the old Virtuoso is first shutdown.  It is advisable that you backup up your
systems before continuing.</para>
<programlisting><![CDATA[
Checking requested components
Checking for existing installations and/or instances of Virtuoso...
 7269 ?        00:06:23 virtuoso
/proc/net/tcp: Permission denied

** Alert: [running processes; ]

** Warning: You have Virtuoso previously installed on this machine.
**
** To avoid existing data being overwritten or lost, you may press ^C to
** exit this installer, terminate and remove the existing installation,
** or proceed taking care to enter non-conflicting data below, by pressing
** Enter.
]]></programlisting>
</listitem>

<listitem>
<para>If you are upgrading a server then the installer will save copies of
old configuration data for later use.</para>
<programlisting><![CDATA[
Preserving any existing configurations...
find: db: No such file or directory
find: demo: No such file or directory
find: bin: No such file or directory
0 blocks
]]></programlisting>
</listitem>

<listitem>
<para>You should have received a license file via email.  This file should be
copied to the server installation directory prior to installation.  The installer
will ask you for its location if none is found.  If you do not have the license
file at this time the installer will still continue.</para>
<programlisting><![CDATA[
Checking licensing...

A license file is required for the Virtuoso Server Instance(s) to
start. Please enter the full path and name of a valid Virtuoso
license file [./virtuoso.lic]:
]]></programlisting>
</listitem>

<listitem>
<para>Now the installer will continue to install files from the package.  Every
file installed will be echoed to the screen.  </para>
<programlisting><![CDATA[
Unpacking enterprise.tar.Z
bin/
bin/v27/
bin/v27/bin/
...
...
vsp/releasenotes.css
vsp/releasenotes.html
vsp/vsp_auth.sql
...done
]]></programlisting>
</listitem>

<listitem>
<para>When the files have been installed from the package the location
supplied for the license file will be checked.  If one is not found then you will
receive the following warning:</para>
<programlisting><![CDATA[
**
**  WARNING: The license file entered is not valid or does not exist.
**           You will need to copy a valid license file manually
**           to the demo and db directories after the Virtuoso installation completes.
]]></programlisting>
</listitem>

<listitem>
<para>The Virtuoso server installation has a few variations.  The next question
from the installer asks which one you want to make default.  Even though each
variation is installed, a convenient symbolic link will be made to
<computeroutput>bin/virtuoso</computeroutput> from the selected type.
Running <computeroutput>ls -l</computeroutput> in the bin directory after
installation will reveal all.</para>
<programlisting><![CDATA[
Checking for installed optional components...
Please choose which Virtuoso server you wish to install:
  1) Universal Server
  2) Universal Server with iODBC
  3) Universal Server with iODBC and support for Java
  4) Universal Server with iODBC and support for PHP
  5) Universal Server with iODBC and support for Java and PHP
  6) Universal Server with iODBC and support for CLR Hosting via Mono
  7) Universal Server with iODBC and support for CLR and Java
  8) Universal Server with iODBC and support for CLR, Java and PHP4

[8] :
]]></programlisting>
</listitem>

<listitem>
<para>The installer will search for required third-party components
depending on which option is selected in the previous step.  For example, choosing
the Virtuoso with Java support will require a Java runtime.  Results of the
search are listed as suggestions from which you can confirm or type
the actual location.</para>
<programlisting><![CDATA[
Attempting to locate the java runtime library (libjvm.so)...

Suggested file locations:
/usr/local/lib
/usr/local/jdk1.3/jre/lib/i386/classic
/usr/local/jdk1.3/jre/lib/i386/server
/usr/local/jdk1.3/jre/lib/i386/client
/usr/opt/blackdown-jdk-1.3.1/jre/lib/i386/classic
/usr/opt/blackdown-jdk-1.3.1/jre/lib/i386/server
/usr/opt/blackdown-jdk-1.3.1/jre/lib/i386/client
/usr/local/jdk1.3/jre/lib/i386/classic
/usr/local/jdk1.3/jre/lib/i386/server
/usr/local/jdk1.3/jre/lib/i386/client

Please select one of the above locations or press Enter to use
the default (/usr/local/jdk1.3/jre/lib/i386/client):
]]></programlisting>
</listitem>

<listitem>
<para>The Virtuoso installer includes a Mono runtime distribution, since
Mono is a developing platform you may have your own installation that you
can supply the path to here.</para>
<programlisting><![CDATA[
Please enter the full path to the Mono installation directory or
Enter to use the default (/home/openlink/virtuoso/mono)
]]></programlisting>
</listitem>

<listitem>
<para>Virtuoso now has enough information to configure its environment and
startup scripts.</para>
<programlisting><![CDATA[
Setting up initial values in scripts and config files
Setting up file bin/odbc.ini
Setting up file bin/odbcinst.ini
Setting up file bin/demo-start.sh
Setting up file bin/demo-stop.sh
Setting up file bin/virtuoso-start.sh
Setting up file bin/virtuoso-stop.sh
Setting up file db/virtuoso.ini
Setting up file demo/demo.ini
Setting up file mono/bin/mcs
Setting up file virtuoso-enterprise.csh
Setting up file virtuoso-enterprise.sh
Setting up file initd_startup.template
Setting up file initd_startup_demo.template
]]></programlisting>
</listitem>

<listitem>
<para>The installer will now ask a series of questions for configuring the
Virtuoso .INI files.  First confirm or alter the default database SQL listener
port number.  This is the port number that this database will be available for
ODBC connections and iSQL sessions.</para>
<programlisting><![CDATA[
Configuring port numbers for default and demo databases

Please enter a port on which to run the default database
SQL listener (default 1111):
]]></programlisting>
</listitem>

<listitem>
<para>Now you must specify the port number of the default database HTTP
listener.  This is the HTTP port that Virtuoso will listen on by default, you web-based
administration interface for Virtuoso will be found here.  If you confirm the
default of 8889, then your Virtuoso will be available from:
<computeroutput>http://server:8889/</computeroutput>, changing
server to the name of your machine appropriately.</para>
<programlisting><![CDATA[
Please enter a port on which to run the default database
HTTP listener (default 8889):
]]></programlisting>
</listitem>

<listitem>
<para>Now you must supply a friendly name that you wish to identify
your Virtuoso server by on the network using Zero Configuration.  </para>
<tip><title>See Also:</title>
<para>The <link linkend="rendezvous">Zero Configuration</link> section.</para></tip>
<programlisting><![CDATA[
Please enter a name for default database Zero Configuration
(default "Virtuoso Universal Server at myserver:1111"):
]]></programlisting>
</listitem>

<listitem>
<para>The Zero Configuration details need a default username to make the connection with.</para>
<programlisting><![CDATA[
Please enter a user name for default database Zero Configuration
(default "dba"):
]]></programlisting>
</listitem>

<listitem>
<para>Now we have all of the above details to supply again for the Demo Virtuoso
database.  The port number supplied here must be different to those supplied previously.</para>
<programlisting><![CDATA[
Please enter a port on which to run the demo database
SQL listener (default 1112):

Please enter a port on which to run the demo database
HTTP listener (default 8890):

Please enter a name for demonstration database Zero Configuration
(default Virtuoso Universal Server (demonstration) at myserver:1112):

Please enter a user name for demonstration database Zero Configuration
(default demo):
]]></programlisting>
</listitem>

<listitem>
<para>The Virtuoso servers have default administrator usernames of "dba".
The "dba" accounts have the default password of "dba".  It is recommended that
you alter this as soon as possibly for security.  The installer now provides the
opportunity to do this the first time the server is started.</para>
<programlisting><![CDATA[
Changing passwords for the Database Universal Server

Please enter a replacement for the Default Database Server's
SQL Administrative (dba) account password (twice) :
Confirm Password :
]]></programlisting>
</listitem>

<listitem>
<para>The Virtuoso servers have default WebDAV administrator usernames
of "dav".   The "dav" accounts have the default password of "dav".  It is
recommended that you alter this as soon as possibly for security.
The installer now provides the opportunity to do this the first time
the server is started.</para>
<programlisting><![CDATA[
Please enter a replacement for the Default Database's
WebDAV administrative (dav) account password (twice) :
Confirm Password :

Please wait while the passwords are changed:

Changing passwords for the Demo Universal Server
]]></programlisting>
</listitem>

<listitem>
<para>Likewise for the Demo server, you can change the default passwords:</para>
<programlisting><![CDATA[
Please enter a replacement for the Demonstration Database Server's
SQL Administrative (dba) account password (twice) :
Confirm Password :

Please enter a replacement for the Demonstration Database Server's
WebDAV Administrative (dav) account password (twice) :
Confirm Password :

Please wait while the passwords are changed:
done.
]]></programlisting>
</listitem>

<listitem>
<para>The file owner and group is changed at the end of the installation.  You
can choose what these shall be set to.  By default the current user is selected.</para>
<programlisting><![CDATA[
Please enter the username:group for the user and group who should own
files in this installation (default: openlink:openlink) :
Setting owners:
]]></programlisting>
</listitem>

<listitem>
<para>Finally the installer can start Virtuoso servers installed for you, but
only if a valid license key has been supplied.</para>
<programlisting><![CDATA[
The Virtuoso Installer has not offered to start a database as
no license key was found. Evaluation users should receive
one via e-mail; in case of difficulties please contact
<Technical.Support@openlinksw.com>.
]]></programlisting>
</listitem>
</orderedlist>
		</sect2>
		
		   <sect2 id="linuxinstpost"><title>Post Installation</title>  
  <sect3 id="linuxinstpostsan">
			<title>Post-Installation Sanity Check</title>
			<para>A quick way to check that the database is running, is to point a browser to the
			http port. The following example URLs will show the System Manager for
			the default, and the demo Virtuoso databases:</para>
			<programlisting>http://example.com
http://example.com
http://a_virtuoso_server.org:8890</programlisting>
		</sect3>
		<sect3 id="linuxinstposttrb"><title>Troubleshooting DB Startup Failures</title>  
  <para><emphasis>Install failure</emphasis></para> 
  <para>Check the .log file in:</para>
<programlisting><![CDATA[
$<Directory where Virtuoso is installed>/bin/virtuoso.log
]]></programlisting>  
 <para>in order to review the installed files binaries and databases (defaults) 
 for issues if install fails.</para>
   <para><emphasis>.lck existance</emphasis></para>   
   <para>Check .log in case of .lck issue</para>
   <para>Delete the .lck file and repeat the steps from above.</para>
   <para><emphasis>.trx incompatiblity issue</emphasis></para>   
   <para>Check .log in case of .trx incompatiblity issue</para>
    <para><emphasis>oplmgr issue</emphasis></para>     
   <para>See <link linkend="oplmngrlfla">OpenLink License Management for Linux</link></para>
  </sect3>
  </sect2>
  
    <sect2 id="linautovirt"><title>Starting Virtuoso Automatically on Reboot</title>

    <para>Two files, named initd_startup.template and
    initd_startup_demo.template, are placed in the top level of the
    Virtuoso installation directory.  On systems using SysVinit (most Linux
    distributions, Solaris) the appropriate one should be copied into
    /etc/init.d/ and symlinks created in the rcN.d/ directories, e.g.:</para>

<programlisting><![CDATA[
bash# cp initd_startup.template /etc/init.d/virtuoso
]]></programlisting>

    <para>Perform some sanity checks here, that the directory it uses exists, etc:</para>

<programlisting><![CDATA[
bash# vi /etc/init.d/virtuoso
]]></programlisting>

    <para>Test that it works correctly:</para>

<programlisting><![CDATA[
bash# /etc/init.d/virtuoso stop
bash# /etc/init.d/virtuoso start
]]></programlisting>

    <para>Finally, create symbolic links in the regular runlevel directories
    pointing to that script:</para>

<programlisting><![CDATA[
bash# cd /etc/rc2.d ; ln -s ../init.d/virtuoso S99virtuoso
bash# cd /etc/rc3.d ; ln -s ../init.d/virtuoso S99virtuoso
bash# cd /etc/rc5.d ; ln -s ../init.d/virtuoso S99virtuoso
]]></programlisting>

    <para>Virtuoso should now start when the service is restarted.</para>
    </sect2>

		<sect2 id="defpasschglin">
			<title>Default passwords</title>
			<para>See the following Quick Start chapter for very important information about
			<link linkend="defpasschange">changing the default passwords</link>.</para>
		</sect2>
	</sect1>
	<sect1 id="unxinstvirt">
		<title>Virtuoso for Unix (Enterprise Edition)</title>
		<sect2 id="b4instunx">
			<title>Before You Install</title>
			<para>To ensure a smooth installation, please review the
      following checklist before you start the setup program.</para>
			<sect3 id="unxdldsw">
				<title>Have you downloaded the software?</title>
				<para>If you have not already done so, please download your copy of OpenLink
      Virtuoso from the Virtuoso web site.  The URL is
		<ulink url="http://www.openlinksw.com/virtuoso/">http://www.openlinksw.com/virtuoso/</ulink>.
		When you visit the site, select &quot;Software Download&quot;.</para>
			</sect3>
			<sect3 id="unxreinstvirt">
				<title>Reinstalling Virtuoso?</title>
				<para>If you are reinstalling Virtuoso, you must first stop the Database Servers.
				You can shut these services down with the following command
				executed from your UNIX shell prompt:</para>
				<programlisting>sh virtuoso-stop.sh </programlisting>
				<para>or</para>
				<programlisting>virtuoso-stop.sh</programlisting>
				<para>or</para>
				<programlisting>./virtuoso-stop.sh</programlisting>
			</sect3>
			<sect3 id="unxfreeports">
				<title>Are ports 1111, 1112, 8889 and 8890 free?</title>
				<para>During the installation you will be prompted for an HTTP port number for
				use by each Virtuoso System Manager. If you are already running a web server
      or other listener on that port, you will encounter problems, and should choose another
      free port when you are prompted.  </para>
				<para>By default, the Virtuoso DBMS listens on port 1111.
      If this port is currently in use by another server then after the installation completes
      you will need to change the port number in the Local Virtuoso ODBC or UDBC DSN that is
      created during the installation process, and also in the following file:</para>
				<programlisting>
$&lt;Installation Directory&gt;/bin/virtuoso.ini</programlisting>
				<para>typically</para>
				<programlisting>/usr/home/virtuoso</programlisting>
				<para>To check if a port is in use you can use the following
      command, and review the output:</para>
				<programlisting>netstat -an | more </programlisting>
			</sect3>
			<sect3 id="unxvirtuser">
				<title>Do you already have a &quot;virtuoso&quot; user
      account on your UNIX system ?</title>
				<para>Please create a UNIX user account called &quot;virtuoso&quot;.</para>
			</sect3>
			<sect3 id="unxiodbcexist">
				<title>Do you already have functional iODBC data sources
      on your system ?</title>
				<para>The OpenLink Virtuoso for UNIX installation presumes the following:</para>
				<simplelist>
					<member>You intend to connect to a Local Virtuoso server using iODBC
          or OpenLink  UDBC</member>
					<member>You intend to connect to one or more Remote Virtuoso servers
          on your network using iODBC or UDBC</member>
					<member>You intend to Attach tables hosted within non-local or
          Remote Virtuoso database servers, into a Local or Remote Virtuoso Server</member>
					<member>The existence of functional OpenLink or third-party iODBC
          drivers for UNIX that connect to the non database servers referred to above.</member>
					<member>In the absence of iODBC drivers for your non Virtuoso
          database, that a functional OpenLink or third-party UDBC Drivers exists for these database
          servers. </member>
				</simplelist>
				<para>If you are using OpenLink Multi-Tier ODBC
      Drivers for your remote database connections then we highly recommend the use of the Web
      Assistant for creating iODBC Data Source Names.</para>
			</sect3>
			<sect3 id="unxiodbcfunc">
				<title>Are your iODBC Data Source Names functional ?</title>
				<para>It is a useful sanity-check to ensure that your iODBC or UDBC
      data sources are functional, OpenLink provides an &quot;odbctest&quot; program for
      verifying basic usability of iODBC data sources. Both of these programs reside in the
      &quot;samples&quot; directory situated beneath the directory into which Virtuoso is
      installed.</para>
			</sect3>
		</sect2>
		<sect2 id="instprocunx"><title>Installation Process</title>
			<para>Once you have downloaded the required tar file from the
web or ftp site and have placed the file in a designated installation directory you are
ready to commence the Virtuoso installation process. </para>
			<para>You may want to specify a new user to own the Virtuoso
installation and then you can place the installation tar file into that users home
directory.</para>
<orderedlist>
  <listitem><para>First step is to un-tar the file to obtain the install script
  and archive file.  Use the following command:</para>
  <programlisting>tar xvf &lt;tar file&gt;.tar</programlisting>
  <para>replacing &lt;tar file&gt; with the relevant name of the file you downloaded.</para></listitem>
  <listitem><para>run the install script using the following command:</para>
<programlisting>[virtuoso@myserver virtuoso]$ sh /install.sh</programlisting>
  <para>The installation process will now begin and prompt you for required information.</para>
</listitem>

<listitem>
<para>The install script will first try and detect running Virtuoso server instances.
In cases where an old Virtuoso server is being upgraded you must ensure that
the old Virtuoso is first shutdown.  It is advisable that you backup up your
systems before continuing.</para>
<programlisting><![CDATA[
Checking requested components
Checking for existing installations and/or instances of Virtuoso...
 7269 ?        00:06:23 virtuoso
/proc/net/tcp: Permission denied

** Alert: [running processes; ]

** Warning: You have Virtuoso previously installed on this machine.
**
** To avoid existing data being overwritten or lost, you may press ^C to
** exit this installer, terminate and remove the existing installation,
** or proceed taking care to enter non-conflicting data below, by pressing
** Enter.
]]></programlisting>
</listitem>

<listitem>
<para>If you are upgrading a server then the installer will save copies of
old configuration data for later use.</para>
<programlisting><![CDATA[
Preserving any existing configurations...
find: db: No such file or directory
find: demo: No such file or directory
find: bin: No such file or directory
0 blocks
]]></programlisting>
</listitem>

<listitem>
<para>You should have received a license file via email.  This file should be
copied to the server installation directory prior to installation.  The installer
will ask you for its location if none is found.  If you do not have the license
file at this time the installer will still continue.</para>
<programlisting><![CDATA[
Checking licensing...

A license file is required for the Virtuoso Server Instance(s) to
start. Please enter the full path and name of a valid Virtuoso
license file [./virtuoso.lic]:
]]></programlisting>
</listitem>

<listitem>
<para>Now the installer will continue to install files from the package.  Every
file installed will be echoed to the screen.  </para>
<programlisting><![CDATA[
Unpacking enterprise.tar.Z
bin/
bin/v27/
bin/v27/bin/
...
...
vsp/releasenotes.css
vsp/releasenotes.html
vsp/vsp_auth.sql
...done
]]></programlisting>
</listitem>

<listitem>
<para>When the files have been installed from the package the location
supplied for the license file will be checked.  If one is not found then you will
receive the following warning:</para>
<programlisting><![CDATA[
**
**  WARNING: The license file entered is not valid or does not exist.
**           You will need to copy a valid license file manually
**           to the demo and db directories after the Virtuoso installation completes.
]]></programlisting>
</listitem>

<listitem>
<para>The Virtuoso server installation has a few variations.  The next question
from the installer asks which one you want to make default.  Even though each
variation is installed, a convenient symbolic link will be made to
<computeroutput>bin/virtuoso</computeroutput> from the selected type.
Running <computeroutput>ls -l</computeroutput> in the bin directory after
installation will reveal all.</para>
<programlisting><![CDATA[
Checking for installed optional components...
Please choose which Virtuoso server you wish to install:
  1) Universal Server
  2) Universal Server with iODBC
  3) Universal Server with iODBC and support for Java
  4) Universal Server with iODBC and support for PHP
  5) Universal Server with iODBC and support for Java and PHP
  6) Universal Server with iODBC and support for CLR Hosting via Mono
  7) Universal Server with iODBC and support for CLR and Java
  8) Universal Server with iODBC and support for CLR, Java and PHP4

[8] :
]]></programlisting>
</listitem>

<listitem>
<para>The installer will search for required third-party components
depending on which option is selected in the previous step.  For example, choosing
the Virtuoso with Java support will require a Java runtime.  Results of the
search are listed as suggestions from which you can confirm or type
the actual location.</para>
<programlisting><![CDATA[
Attempting to locate the java runtime library (libjvm.so)...

Suggested file locations:
/usr/local/lib
/usr/local/jdk1.3/jre/lib/i386/classic
/usr/local/jdk1.3/jre/lib/i386/server
/usr/local/jdk1.3/jre/lib/i386/client
/usr/opt/blackdown-jdk-1.3.1/jre/lib/i386/classic
/usr/opt/blackdown-jdk-1.3.1/jre/lib/i386/server
/usr/opt/blackdown-jdk-1.3.1/jre/lib/i386/client
/usr/local/jdk1.3/jre/lib/i386/classic
/usr/local/jdk1.3/jre/lib/i386/server
/usr/local/jdk1.3/jre/lib/i386/client

Please select one of the above locations or press Enter to use
the default (/usr/local/jdk1.3/jre/lib/i386/client):
]]></programlisting>
</listitem>

<listitem>
<para>The Virtuoso installer includes a Mono runtime distribution, since
Mono is a developing platform you may have your own installation that you
can supply the path to here.</para>
<programlisting><![CDATA[
Please enter the full path to the Mono installation directory or
Enter to use the default (/home/openlink/virtuoso/mono)
]]></programlisting>
</listitem>

<listitem>
<para>Virtuoso now has enough information to configure its environment and
startup scripts.</para>
<programlisting><![CDATA[
Setting up initial values in scripts and config files
Setting up file bin/odbc.ini
Setting up file bin/odbcinst.ini
Setting up file bin/demo-start.sh
Setting up file bin/demo-stop.sh
Setting up file bin/virtuoso-start.sh
Setting up file bin/virtuoso-stop.sh
Setting up file db/virtuoso.ini
Setting up file demo/demo.ini
Setting up file mono/bin/mcs
Setting up file virtuoso-enterprise.csh
Setting up file virtuoso-enterprise.sh
Setting up file initd_startup.template
Setting up file initd_startup_demo.template
]]></programlisting>
</listitem>

<listitem>
<para>The installer will now ask a series of questions for configuring the
Virtuoso .INI files.  First confirm or alter the default database SQL listener
port number.  This is the port number that this database will be available for
ODBC connections and iSQL sessions.</para>
<programlisting><![CDATA[
Configuring port numbers for default and demo databases

Please enter a port on which to run the default database
SQL listener (default 1111):
]]></programlisting>
</listitem>

<listitem>
<para>Now you must specify the port number of the default database HTTP
listener.  This is the HTTP port that Virtuoso will listen on by default, you web-based
administration interface for Virtuoso will be found here.  If you confirm the
default of 8889, then your Virtuoso will be available from:
<computeroutput>http://server:8889/</computeroutput>, changing
server to the name of your machine appropriately.</para>
<programlisting><![CDATA[
Please enter a port on which to run the default database
HTTP listener (default 8889):
]]></programlisting>
</listitem>

<listitem>
<para>Now you must supply a friendly name that you wish to identify
your Virtuoso server by on the network using Zero Configuration.  </para>
<tip><title>See Also:</title>
<para>The <link linkend="rendezvous">Zero Configuration</link> section.</para></tip>
<programlisting><![CDATA[
Please enter a name for default database Zero Configuration
(default "Virtuoso Universal Server at myserver:1111"):
]]></programlisting>
</listitem>

<listitem>
<para>The Zero Configuration details need a default username to make the connection with.</para>
<programlisting><![CDATA[
Please enter a user name for default database Zero Configuration
(default "dba"):
]]></programlisting>
</listitem>

<listitem>
<para>Now we have all of the above details to supply again for the Demo Virtuoso
database.  The port number supplied here must be different to those supplied previously.</para>
<programlisting><![CDATA[
Please enter a port on which to run the demo database
SQL listener (default 1112):

Please enter a port on which to run the demo database
HTTP listener (default 8890):

Please enter a name for demonstration database Zero Configuration
(default Virtuoso Universal Server (demonstration) at myserver:1112):

Please enter a user name for demonstration database Zero Configuration
(default demo):
]]></programlisting>
</listitem>

<listitem>
<para>The Virtuoso servers have default administrator usernames of "dba".
The "dba" accounts have the default password of "dba".  It is recommended that
you alter this as soon as possibly for security.  The installer now provides the
opportunity to do this the first time the server is started.</para>
<programlisting><![CDATA[
Changing passwords for the Database Universal Server

Please enter a replacement for the Default Database Server's
SQL Administrative (dba) account password (twice) :
Confirm Password :
]]></programlisting>
</listitem>

<listitem>
<para>The Virtuoso servers have default WebDAV administrator usernames
of "dav".   The "dav" accounts have the default password of "dav".  It is
recommended that you alter this as soon as possibly for security.
The installer now provides the opportunity to do this the first time
the server is started.</para>
<programlisting><![CDATA[
Please enter a replacement for the Default Database's
WebDAV administrative (dav) account password (twice) :
Confirm Password :

Please wait while the passwords are changed:

Changing passwords for the Demo Universal Server
]]></programlisting>
</listitem>

<listitem>
<para>Likewise for the Demo server, you can change the default passwords:</para>
<programlisting><![CDATA[
Please enter a replacement for the Demonstration Database Server's
SQL Administrative (dba) account password (twice) :
Confirm Password :

Please enter a replacement for the Demonstration Database Server's
WebDAV Administrative (dav) account password (twice) :
Confirm Password :

Please wait while the passwords are changed:
done.
]]></programlisting>
</listitem>

<listitem>
<para>The file owner and group is changed at the end of the installation.  You
can choose what these shall be set to.  By default the current user is selected.</para>
<programlisting><![CDATA[
Please enter the username:group for the user and group who should own
files in this installation (default: openlink:openlink) :
Setting owners:
]]></programlisting>
</listitem>

<listitem>
<para>Finally the installer can start Virtuoso servers installed for you, but
only if a valid license key has been supplied.</para>
<programlisting><![CDATA[
The Virtuoso Installer has not offered to start a database as
no license key was found. Evaluation users should receive
one via e-mail; in case of difficulties please contact
<Technical.Support@openlinksw.com>.
]]></programlisting>
</listitem>
</orderedlist>
		</sect2>
		
   <sect2 id="unxinstvirtinstpost"><title>Post Installation</title>  
  <sect3 id="unxinstvirtpost">
			<title>Post-Installation Sanity Check</title>
			<para>A quick way to check that the database is running, is to point a browser to the
			http port. The following example URLs will show the System Manager for
			the default, and the demo Virtuoso databases:</para>
			<programlisting>http://example.com
http://example.com
http://a_virtuoso_server.org:8890</programlisting>
		</sect3>
		<sect3 id="unxinstvirtinstposttrb"><title>Troubleshooting DB Startup Failures</title>  
  <para><emphasis>Install failure</emphasis></para> 
  <para>Check the .log file in:</para>
<programlisting><![CDATA[
$<Directory where Virtuoso is installed>/bin/virtuoso.log
]]></programlisting>  
 <para>in order to review the installed files binaries and databases (defaults) 
 for issues if install fails.</para>
   <para><emphasis>.lck existance</emphasis></para>   
   <para>Check .log in case of .lck issue</para>
   <para>Delete the .lck file and repeat the steps from above.</para>
   <para><emphasis>.trx incompatiblity issue</emphasis></para>   
   <para>Check .log in case of .trx incompatiblity issue</para>
    <para><emphasis>oplmgr issue</emphasis></para>     
   <para>See <link linkend="oplmngrlfla">OpenLink License Management for Linux</link></para>
  </sect3>
  </sect2>

    <sect2 id="unxautovirt"><title>Starting Virtuoso Automatically on Reboot</title>

    <para>Two files, named initd_startup.template and
    initd_startup_demo.template, are placed in the top level of the
    Virtuoso installation directory.  On systems using SysVinit (most Linux
    distributions, Solaris) the appropriate one should be copied into
    /etc/init.d/ and symlinks created in the rcN.d/ directories, e.g.:</para>

<programlisting><![CDATA[
bash# cp initd_startup.template /etc/init.d/virtuoso
]]></programlisting>

    <para>Perform some sanity checks here, that the directory it uses exists, etc:</para>

<programlisting><![CDATA[
bash# vi /etc/init.d/virtuoso
]]></programlisting>

    <para>Test that it works correctly:</para>

<programlisting><![CDATA[
bash# /etc/init.d/virtuoso stop
bash# /etc/init.d/virtuoso start
]]></programlisting>

    <para>Finally, create symbolic links in the regular runlevel directories
    pointing to that script:</para>

<programlisting><![CDATA[
bash# cd /etc/rc2.d ; ln -s ../init.d/virtuoso S99virtuoso
bash# cd /etc/rc3.d ; ln -s ../init.d/virtuoso S99virtuoso
bash# cd /etc/rc5.d ; ln -s ../init.d/virtuoso S99virtuoso
]]></programlisting>

    <para>Virtuoso should now start when the service is restarted.</para>
    </sect2>

    <sect2 id="defpasschgunx">
			<title>Default passwords</title>
			<para>See the following Quick Start chapter for very important information about
			<link linkend="defpasschange">changing the default passwords</link>.</para>
		</sect2>
	</sect1>
	-->

<sect1 id="virtuosoinstallunixpe">
  <title>Installing the Virtuoso Universal Server on Unix-like OS (AIX, HP-UX, Linux, Solaris, etc.) </title>
  <sect2 id="virtuosoinstallunixpedescr">
    <title>Installation</title>
    <para>Once the required tar file has been downloaded from the web or ftp site and placed in a designated installation
    	directory the installation process is ready to commence.
    </para>
    <itemizedlist>
      <listitem>Choose or create a suitable user account to own your Virtuoso installation.</listitem>
      <listitem>Un-tar the file to obtain the install script and archive file using a command like this, where XX specifies the
      	OS identifier (e.g., l3 = Linux glibc23 x86, l9 = Linux glibc25 x86_64, sv = Solaris 2.10 x86_64, etc.):
<programlisting><![CDATA[
tar -xvf XXvpz2zz.tar
]]></programlisting>
      </listitem>
      <listitem>If a license file exists, place this in the same directory as the installation files, and it will automatically
      	be applied during installation. If upgrading an existing Virtuoso instance, be sure to take a backup of your database
      	file and shut down the existing instance before proceeding.
      </listitem>
      <listitem>Run the install script using the following command:
<programlisting><![CDATA[
$ sh ./install.sh

- Extracting Virtuoso Universal Server vX.Y

- Creating default environment settings

- Creating default database settings
Installing new virtuoso.ini in $VIRTUOSO_HOME/database
Installing new php.ini in $VIRTUOSO_HOME/database
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t

- Registering ODBC drivers

- Registering .NET provider for Mono

- Installing VAD packages in database (this can take some time)

- Checking where license should be stored

- Starting OpenLink License Manager

- Checking for initial Virtuoso license

- Starting Virtuoso server instance

- Finalizing installation


This concludes the first part of the installation.


Please start a browser manually and open the following URL to finalize
the installation process:

     http://<hostname>:8890/install/


Installation completed
$
]]></programlisting>
       </listitem>
       <listitem>Proceed to the Configuration section below.</listitem>
    </itemizedlist>
</sect2>
<sect2 id="virtuosoinstallunixpeconfg">
    <title>Configuration</title>
    <itemizedlist>
      <listitem>Once the URL above has been loaded into a browser, you can select a license file for use with the installation;
      	if a license file is already in place, you can "Skip" this task with the obvious button:
        <figure id="v50peunx00" float="1">
          <title>License file</title>
	  <graphic fileref="inst/v50-pe-unx-00.png"/>
        </figure>
      </listitem>
      <listitem>It is strongly advised that the standard "dba" and "dav" user account password be changed using the post installation
      	page provided:
        <figure id="v50peunx01" float="1">
          <title>DAV/DBA authentication Setting page</title>
	  <graphic fileref="inst/v50-pe-unx-01.png"/>
        </figure>
      </listitem>
      <listitem>The post installation page is now complete and the Virtuoso Welcome page is presented:
        <figure id="v50peunx02" float="1">
          <title>Post installation page</title>
	  <graphic fileref="inst/v50-pe-unx-02.png"/>
        </figure>
      </listitem>
      <listitem>The installation is now ready for use.</listitem>
    </itemizedlist>
</sect2>
        <sect2 id="installdemopersonaledition">
		<title>Demo Database</title>
           <para><link linkend="demodbinstallsteps">Installation steps</link>.</para>
        </sect2>
</sect1>
<!-- This need to be merged with http://wikis.openlinksw.com/dataspace/owiki/wiki/VirtuosoWikiWeb/VirtuosoInstallMac-->
<sect1 id="installmacosx"><title>Virtuoso for Mac OS X</title>
  <sect2 id="macosxbeforeuinst"><title>Before You Install</title>
  <para>Before installing the Virtuoso software for Mac OS X you must ensure
  that you have the correct package from the <ulink url="http://virtuoso.openlinksw.com/download/">OpenLink</ulink>
  Web Site.</para>

	</sect2>
    <sect2 id="macosxinstdragdrop"><title>Virtuoso Drag and Drop Installer for Mac OS X</title>
      <para><emphasis>Note</emphasis>: Virtuoso 7 and its Drag-and-Drop Installer for Mac OS X require Lion
      (10.7.x), Mountain Lion (10.8.x), Mavericks (10.9.x), or later. Virtuoso 6 remains available for
      deployment on Leopard (10.5.x) or Snow Leopard (10.6.x).</para>
      <orderedlist>
         <listitem><ulink url="http://virtuoso.openlinksw.com/download/">Download</ulink> and double-click on
         the Virtuoso installer disk image, <emphasis>mwvp2zzz.dmg</emphasis>, to start the installation.
           <figure id="v7pe1" float="1">
             <title>Mac OS X installer: Start installation</title>
             <graphic fileref="mac/v7pe1.png" width="101" depth="84"/>
           </figure>
         </listitem>
         <listitem>Drag the Virtuoso application icon to your Applications folder (recommended) or any
         	preferred location on your Mac.
           <figure id="v7pe2" float="1">
             <title>Mac OS X installer: Drag Virtuoso Application</title>
             <graphic fileref="mac/v7pe2.png" width="602" depth="472"/>
           </figure>
         </listitem>
         <listitem>Double-click the Virtuoso application (e.g., Virtuoso 7.1.app) to launch the Virtuoso
         	Application Manager Menu Extra, which will display as a V symbol in the menu bar.
           <figure id="v7pe6" float="1">
             <title>Mac OS X installer: Drag Virtuoso Application</title>
             <graphic fileref="mac/v7pe6.png" width="97" depth="19"/>
           </figure>
         </listitem>
         <listitem>Select <emphasis>Start Default Instance</emphasis> from the <emphasis>V</emphasis> menu.
           <figure id="v7pe7" float="1">
             <title>Mac OS X installer: Drag Virtuoso Application</title>
             <graphic fileref="mac/v7pe7.png" width="266" depth="170"/>
           </figure>
         </listitem>
         <listitem>If this is a first time installation of OpenLink components, a dialog will be prompt you
         	to install the OpenLink License Manager.
           <figure id="v7pe8" float="1">
             <title>Mac OS X installer: Drag Virtuoso Application</title>
             <graphic fileref="mac/v7pe8.png" width="422" depth="213"/>
           </figure>
           <orderedlist>
             <listitem>Click the <emphasis>Continue</emphasis> button to start the installation.
               <figure id="v7pe9" float="1">
                 <title>Mac OS X installer: Drag Virtuoso Application</title>
                 <graphic fileref="mac/v7pe9.png" width="619" depth="443"/>
               </figure>
             </listitem>
             <listitem>Select the disk the installation should be performed on.
               <figure id="v7pe10" float="1">
                 <title>Mac OS X installer: Drag Virtuoso Application</title>
                 <graphic fileref="mac/v7pe10.png" width="621" depth="441"/>
               </figure>
             </listitem>
             <listitem>Click <emphasis>Install</emphasis> to commence the installation of the License Manager
             components.
             	 <figure id="v7pe11" float="1">
                 <title>Mac OS X installer: Drag Virtuoso Application</title>
                 <graphic fileref="mac/v7pe11.png" width="619" depth="442"/>
               </figure>
             </listitem>
             <listitem>The following dialog will be displayed to confirm successful installation of the License
             	Manager, which will be automatically started and ready for use upon installation.
               <figure id="v7pe12" float="1">
                 <title>Mac OS X installer: Drag Virtuoso Application</title>
                 <graphic fileref="mac/v7pe12.png" width="624" depth="445"/>
               </figure>
             </listitem>
           </orderedlist>
         </listitem>
         <listitem>If a license file is not already in place, you will be prompted to locate an available
         	license file or to purchase one for installation. Click the Install button to install the license
         	file of your choice.
           <figure id="v7pe13" float="1">
             <title>Mac OS X installer: Drag Virtuoso Application</title>
             <graphic fileref="mac/v7pe13.png" width="423" depth="217"/>
           </figure>
           <orderedlist>
             <listitem>Navigate to the location of the license file to be installed, and click the
             	<emphasis>Open</emphasis> button. The installer will move it into the
             	<emphasis>/Library/Application Support/openlink/Licenses/</emphasis> folder.
               <figure id="v7pe14" float="1">
                 <title>Mac OS X installer: Drag Virtuoso Application</title>
                 <graphic fileref="mac/v7pe14.png" width="700" depth="400"/>
               </figure>
             </listitem>
             <listitem>A dialog confirming the successful installation of the license file will be displayed.
               <figure id="v7pe15" float="1">
                 <title>Mac OS X installer: Drag Virtuoso Application</title>
                 <graphic fileref="mac/v7pe15.png" width="422" depth="155"/>
               </figure>
             </listitem>
           </orderedlist>
         </listitem>
         <listitem>The Default database instance can now be started by clicking the <emphasis>Start</emphasis>
         button.
           <figure id="v7pe16" float="1">
             <title>Mac OS X installer: Drag Virtuoso Application</title>
             <graphic fileref="mac/v7pe16.png" width="420" depth="157"/>
           </figure>
         </listitem>
         <listitem>The Virtuoso server is now ready for use, and the browser-based Virtuoso Conductor
         	administration interface may be accessed by selecting <emphasis>Open Virtuoso Conductor</emphasis>
         	from the <emphasis>V</emphasis> menu.
           <figure id="v7pe17" float="1">
             <title>Mac OS X installer: Drag Virtuoso Application</title>
             <graphic fileref="mac/v7pe17.png" width="264" depth="167"/>
           </figure>
         </listitem>
         <listitem>The Virtuoso Conductor may also be accessed by manually loading the URL
         	&lt;http://example.com/conductor&gt; (or &lt;http://full-hostname.example.com:8890/conductor&gt;
         	from a remote host) into any web browser.
           <figure id="v7pe18" float="1">
             <title>Mac OS X installer: Drag Virtuoso Application</title>
             <graphic fileref="mac/v7pe18.png" width="700" depth="432"/>
           </figure>
         </listitem>
      </orderedlist>
    <sect3 id="macosxinstdragdroptrbsh"><title>Troubleshooting</title>
      <para>Many issues may be quickly diagnosed and resolved by reviewing Virtuoso's <code>.log</code> file,
      typically located alongside the active <code>.db</code> file. </para>
      <figure id="v7pe19" float="1">
        <title>Mac OS X installer: Troubleshooting</title>
        <graphic fileref="mac/v7pe19.png" width="700" depth="498"/>
      </figure>
      <para>The default instance log file may be opened in Mac OS X's Console.app by:</para>
      <itemizedlist mark="bullet">
        <listitem>selecting <emphasis>Open Diagnostic Messages</emphasis> from the <emphasis>V</emphasis> menu</listitem>
        <listitem>right-clicking on the <emphasis>Virtuoso 7.1.app </emphasis> icon, select
        <emphasis>View Package Contents</emphasis>, and then drilling down to
        <emphasis>Contents -> virtuoso -> database -> virtuoso.log</emphasis>
          <figure id="v7pe20" float="1">
            <title>Mac OS X installer: Troubleshooting</title>
            <graphic fileref="mac/v7pe20.png" width="700" depth="492"/>
          </figure>
        </listitem>
        <listitem>executing the following command in <emphasis>Terminal.app</emphasis>:
<programlisting><![CDATA[
open /Applications/Virtuoso\ 7.1.app/Contents/virtuoso/database/virtuoso.log
]]></programlisting>
        </listitem>
      </itemizedlist>
      <sect4 id="macosxinstdragdroptrbshmissingl"><title>Missing license file</title>
        <para>Make sure that the license file, always named <code>virtuoso.lic</code> is in the correct
        location, as described above -- <code>/Library/Application Support/openlink/Licenses/.</code></para>
        <para>Restarting the License Manager may be necessary. Rebooting should always result in a running License Manager, but you can also use the <emphasis>Terminal.app</emphasis>:</para>
<programlisting><![CDATA[
cd /Library/Application\ Support/openlink/bin
./oplmgr -fd /Library/Application\ Support/openlink/Licenses
]]></programlisting>
      </sect4>
      <sect4 id="macosxinstdragdroptrbshexpiredl"><title>Expired license file</title>
        <para>Acquire a non-expired license file, by purchase or conversation with Technical Support or your
        	Account Manager, and replace the expired file with the non-expired, as
        	<ulink url="http://support.openlinksw.com/supportweb/ApplyVirtLicenses">documented</ulink>.</para>
      </sect4>
      <sect4 id="macosxinstdragdroptrbsnolm"><title>Cannot contact the License Manager</title>
        <para>Rebooting should always result in a running License Manager. You can use
        	<emphasis>Terminal.app</emphasis> to check whether it's running:</para>
<programlisting><![CDATA[
ps -ef | grep oplmgr | grep -v grep
]]></programlisting>
        <para>If no process is listed, these two commands should get it running:</para>
<programlisting><![CDATA[
cd /Library/Application\ Support/openlink/bin
./oplmgr -fd ../Licenses
]]></programlisting>
        <para>If the process is listed, there are many possible causes, including firewall or other networking
        	issues. Please <ulink url="http://support.openlinksw.com/support/online-support.vsp">allow our Support Team</ulink>
        	to assist you in diagnosis and resolution.
        </para>
      </sect4>
    </sect3>
  </sect2>
  <sect2 id="macosxinst"><title>Installing Virtuoso 6 or earlier</title>

  <para>Open the Virtuoso Personal Edition Disk Image file ntvpz2zz.dmg by either double clicking on
        the DMG file in the Finder windows or using the &quot;open&quot; command from a Terminal window, to mount
        the Disk Image containing the VirtuosoPersonalEdition.mpkg installer.
  </para>

  <figure id="v50pe00" float="1"><title>Mounting the Disk Image</title>
    <graphic fileref="mac/v50pe00.png" width="250" depth="217"/></figure>

  <para>The installer will load the Introduction page.
  </para>

  <figure id="v50pe01" float="1"><title>Installer Introduction Page</title>
    <graphic fileref="mac/v50pe01.png" width="626" depth="445"/></figure>

  <para>Review the Readme page for any important information concerning the product installation.
  </para>

  <figure id="v50pe02" float="1"><title>Important Information</title>
    <graphic fileref="mac/v50pe02.png" width="624" depth="441"/></figure>

  <para>Read the license agreement and &quot;agree&quot; to the terms.
  </para>

  <figure id="v50pe03" float="1"><title>Software License Agreement</title>
    <graphic fileref="mac/v50pe03.png" width="621" depth="442"/></figure>

  <para>Select the Destination volume the software is to be installed on.
  </para>

  <figure id="v50pe04" float="1"><title>Select Destination</title>
    <graphic fileref="mac/v50pe04.png" width="622" depth="440"/></figure>

  <para>Choose to perform and Easy(default) installation or click on the &quot;customize&quot; button to perform a Custom installation.
  </para>

  <figure id="v50pe05" float="1"><title>Selecting the Type of Installation</title>
    <graphic fileref="mac/v50pe05.png" width="622" depth="440"/></figure>

  <para>If the &quot;Custom&quot; option was selected in the previous step then select the packages to be installed.
  </para>

  <figure id="v50pe06" float="1"><title>Customizing the Installation</title>
    <graphic fileref="mac/v50pe06.png" width="619" depth="449"/></figure>


  <para>The software must be install by a user with Administrative privileges on the machine.
  </para>

  <figure id="v50pe07" float="1"><title>Identifying yourself as Administrator</title>
    <graphic fileref="mac/v50pe07.png" width="437" depth="238"/></figure>

  <para>The software components will be installed the status of which is indicated by the progress bar.
  </para>

  <figure id="v50pe08" float="1"><title>Preparing ... </title>
    <graphic fileref="mac/v50pe08.png" width="623" depth="441"/></figure>

  <para>The Virtuoso Server is started at the end of this process. A Web page is loaded to enable you to obtain a trial or full license from the OpenLink online shop:
  </para>
  
  <figure id="v50pe09" float="1"><title>Admin Assistant</title>
    <graphic fileref="mac/v50pe09.png" width="737" depth="361"/></figure>

  <para>Choose to obtain a Trial license for an evaluation or enter the shop site to purchase a full license.
  </para>

  <figure id="v50pe10" float="1"><title>The Trial license page</title>
    <graphic fileref="mac/v50pe10.png" width="905" depth="693"/></figure>

  <para>Click on the &quot;Download License&quot; button on the right to obtain the license file immediately. An e-mail will also be sent to your registered email address. This email contains the details of the Virtuoso license and the location of an OpenLink Data Spaces account where you can obtain an additional demo license at a later date.
  </para>
  <para>Once a license file is available on your Mac, use the &quot;Browse&quot; button to locate it. Then, use the
  &quot;Set License&quot; button to initialize the Virtuoso server with it:</para>
  <figure id="v50pe11" float="1"><title>Download license</title>
    <graphic fileref="mac/v50pe11.png" width="881" depth="759"/></figure>

  <para>Change the &quot;dba&quot; and &quot;dav&quot; user passwords from their default of &quot;dba&quot; and
  &quot;dav&quot; to a value of your choice:
  </para>

  <figure id="v50pe12" float="1"><title>Change passwords</title>
    <graphic fileref="mac/v50pe12.png" width="858" depth="503"/></figure>

  <para>The Virtuoso Server Welcome page will now be displayed. The server is online. This Web based page can be used for general configuration and usage of the Virtuoso Server:
  </para>

  <figure id="v50pe13" float="1"><title>Welcome</title>
    <graphic fileref="mac/v50pe13.png" width="766" depth="622"/></figure>

  <para>The Installation is now complete.
  </para>

  <figure id="v50pe14" float="1"><title>Installation complete</title>
    <graphic fileref="mac/v50pe14.png" width="623" depth="439"/></figure>

  	</sect2>

        <sect2 id="macosxconfigur"><title>Configuration</title>

  <para>Click on the &quot;Conductor&quot; link in the left frame of the Welcome page to load the
        Virtuoso Conductor which is the Administration interface for the installation.
        Enter the &quot;dba&quot; username and password to login.
  </para>

  <figure id="v50pe15" float="1"><title>Configuration</title>
    <graphic fileref="mac/v50pe15.png" width="877" depth="752"/></figure>

  <para>Once logged into the conductor click on any of the &quot;Tabs&quot; along the top to Administer the various
        features of the Virtuoso Universal Server installation.
  </para>

  <figure id="v50pe16" float="1"><title>Various features using Conductor Tabs</title>
    <graphic fileref="mac/v50pe16.png" width="878" depth="749"/></figure>

  <para>Apple scripts for starting and stopping your Virtuoso Universal Server installation are located in
        the &quot;/Application/OpenLink Virtuoso&quot; folder of the machine.
  </para>

  <figure id="v50pe17" float="1"><title>Location of apple scripts</title>
    <graphic fileref="mac/v50pe17.png" width="377" depth="438"/></figure>

        </sect2>

   <sect2 id="macosxinstpost"><title>Post Installation</title>  
  <sect3 id="macosxinstpostsan">
		<title>Post-Installation Sanity Check</title>
		<para>A quick way to check that the database is running, is to point a browser to the
		http port. The following example URLs will show the System Manager for
		the default, and the demo Virtuoso databases:</para>
		<programlisting>http://example.com
http://example.com
http://a_virtuoso_server.org:8890</programlisting>
	</sect3> 
  <sect3 id="macosxinstposttrb"><title>Troubleshooting DB Startup Failures</title>  
  <para><emphasis>Install failure</emphasis></para> 
  <para>Check the .log file in oplmgr (License Manager) location: <code>/Library/Application Support/openlink/bin/</code>, which is for the database 
  and log files etc. in order to review the installed files binaries and databases (defaults) 
  for issues if install fails.</para>
  
      <figure id="instmac" float="1">
       <title>The .log file</title>
       <graphic fileref="ui/instmac.png"/>
     </figure>
   <para><emphasis>.lck existance</emphasis></para>   
   <para>Check .log in case of .lck issue</para>
   <para>Delete the .lck file and repeat the steps from above.</para>
   <para><emphasis>.trx incompatiblity issue</emphasis></para>   
   <para>Check .log in case of .trx incompatiblity issue</para>
    <para><emphasis>oplmgr issue</emphasis></para>     
   <para>To stop, start, or reload (which updates licenses) use the following commands: </para>
<programlisting><![CDATA[
/Library/Application Support/openlink/bin/oplmgr +start | +stop | +reload	
]]></programlisting>
      <figure id="instmac2" float="1">
       <title>The .log file</title>
       <graphic fileref="ui/instmac2.png"/>
     </figure>
     <tip><title>See Also:</title>
     <para><link linkend="oplmgr">OpenLink License Management</link></para>
     </tip>
  </sect3>
  </sect2>
  
	<sect2 id="macosxodbcdsnconf"><title>Configuring an ODBC Data Source</title>

	  <para>Launch the iODBC Administrator, assuming that you have the iODBC
		Administrator installed.</para>

		<para>On some Mac OS X systems installed on an HFS partition, the icons may
		not be displayed correctly or at all, due to a Mac OS X bug.  In such cases
		a simple reboot of your system should correct this.</para>

		<para>Once the iODBC Administrator window has appeared you can press the
		<emphasis>Add</emphasis> button on the either the <emphasis>User DSN</emphasis>
		or the <emphasis>System DSN</emphasis> panel to add a new Data Source entry.</para>

  <figure id="macconfig01" float="1"><title>ODBC Administrator</title>
    <graphic fileref="mac/config01.jpg"/></figure>

		<para>Choose the driver that you wish to create a Data Source for, in this
		case the Virtuoso Driver (3.0).</para>

  <figure id="macconfig02" float="1"><title>ODBC Administrator - Choose Virtuoso Driver</title>
    <graphic fileref="mac/config03.jpg"/></figure>

		<para>Provide all required details in the fields provided by the setup panel.</para>

  <figure id="macconfig03" float="1"><title>ODBC Administrator - Configure Virtuoso DSN</title>
    <graphic fileref="mac/config04.jpg"/></figure>

	<para>The server can be picked from the list of Zero Configuration Datasources
	that is discovered.</para>

  <figure id="osximage23" float="1"><title>Pick Zero Config</title>
    <graphic fileref="mac/osximage23.gif" /></figure>

	<para>Alternatively a manual selection can be made for the server.</para>

  <figure id="osximage25" float="1"><title>Pick manual mode</title>
    <graphic fileref="mac/osximage25.gif" /></figure>

	<para>In this case enter the hostname (or IP) and port number.</para>

  <figure id="osximage34" float="1"><title>Manual Server Entry</title>
    <graphic fileref="mac/osximage34.gif" /></figure>


  <figure id="macconfig04" float="1"><title>ODBC Administrator - Configure Virtuoso DSN</title>
    <graphic fileref="mac/config05.jpg"/></figure>

  <figure id="macconfig06" float="1"><title>ODBC Administrator - Configure Virtuoso DSN</title>
    <graphic fileref="mac/config06.jpg"/></figure>

		<para>Press the <emphasis>Finish</emphasis> button to save the Data Source
		information.</para>

	</sect2>

	<sect2 id="macosxodbcdsntest"><title>Testing an ODBC Data Source</title>

		<para>Select the Data Source from the DSN list, and press the <emphasis>Test</emphasis>
		button.</para>

		<para>You will be prompted for a username and password to establish a
		connection with the Data Source.</para>

  <figure id="macconfig07" float="1"><title>Login - Identity Tab</title>
    <graphic fileref="mac/config07.jpg" /></figure>

<para>The login dialogue also allows you to
		alter the configuration if required.</para>

		<para>Under the Connection Tab are the fields for the remote server,
		and the authentication method. Typically the defaults are used.</para>

  <figure id="macconfig30" float="1"><title>Login - Connection Tab</title>
    <graphic fileref="mac/osximage30.gif" /></figure>

		<para>The Options page has Database, Charset and daylight savings
		configuration. Typically the defaults are used.</para>

  <figure id="macconfig31" float="1"><title>Login - Options Tab</title>
    <graphic fileref="mac/osximage31.gif" /></figure>

		<para>The About page shows the software details.</para>

  <figure id="macconfig32" float="1"><title>Login - About</title>
    <graphic fileref="mac/osximage32.gif" /></figure>

		<para>The result of the test is shown in a popup window.</para>

  <figure id="macconfig33" float="1"><title>Test Result</title>
    <graphic fileref="mac/osximage33.gif" /></figure>

	</sect2>

	<sect2 id="defpasschgmac">
		<title>Default passwords</title>
		<para>See the following Quick Start chapter for very important information about
		<link linkend="defpasschange">changing the default passwords</link>.</para>
	</sect2>
        <sect2 id="installdemomac">
		<title>Demo Database</title>
<para><link linkend="demodbinstallsteps">Installation steps</link>.</para>
        </sect2>

</sect1>


<sect1 id="oplmgr">
  <title>OpenLink License Management</title>
  <sect2 id="oplmngrlf"><title>License Files</title>
    <sect3 id="oplmngrlfla"><title>License Activation</title>
      <sect4 id="oplmngrlfla"><title>Mac OS X</title>
        <orderedlist>
          <listitem>Launch <computeroutput>Terminal.app (/Applications/Utilities/)</computeroutput></listitem>
          <listitem>Execute the command <computeroutput>cd "/Library/Application Support/openlink/bin/"</computeroutput></listitem>
          <listitem>Execute the command <computeroutput>oplmgr +stop</computeroutput></listitem>
          <listitem>Retrieve your new Virtuoso license file from an email or <link linkend="oplmngrlflb">ODS Briefcase</link>.</listitem>
          <listitem>Replace the old license file with the new license file. (You may delete the old file, or safely retain it in this location by changing the <computeroutput>.lic</computeroutput> file extension to <computeroutput>.lic-old</computeroutput>.)</listitem>
          <listitem>Execute the command <computeroutput>oplmgr +start</computeroutput></listitem>
        </orderedlist>
      </sect4>
      <sect4 id="oplmngrlfla"><title>Windows</title>
        <orderedlist>
          <listitem>Launch the <emphasis>Services</emphasis> Control Panel (may be in the <emphasis>Administrative Tools</emphasis> sub-folder).</listitem>
          <listitem>Locate and select the <emphasis>OpenLink License Manager service</emphasis>.</listitem>
          <listitem>Click the <emphasis>Stop</emphasis> icon.</listitem>
          <listitem>Retrieve your new Virtuoso license file from an email or <link linkend="oplmngrlflb">ODS Briefcase</link>.</listitem>
          <listitem>Replace the old license file with the new license file. (You may delete the old file, or safely retain it in this location by changing the <computeroutput>.lic</computeroutput> file extension to <computeroutput>.lic-old</computeroutput>.)</listitem>
          <listitem>Go back to the <emphasis>Services</emphasis> Control Panel.</listitem>
          <listitem>Locate and select the <emphasis>OpenLink License Manager</emphasis> service.</listitem>
          <listitem>Click the <emphasis>Start</emphasis> icon.</listitem>
        </orderedlist>
      </sect4>
      <sect4 id="oplmngrlfla"><title>Unix-like OS (AIX, HP-UX, Linux, Solaris, etc.)</title>
        <orderedlist>
          <listitem>Open a Unix terminal.</listitem>
          <listitem><computeroutput>cd</computeroutput> into the root of your Virtuoso installation.</listitem>
          <listitem>Use one of the following commands to set Virtuoso-related environment variables. (Note that they do, and must, begin with dot-space-dot-slash.)
            <itemizedlist>
              <listitem><computeroutput>. ./virtuoso-enterprise.sh</computeroutput> - bash, bsh, ksh, and related shells</listitem>
              <listitem><computeroutput>. ./virtuoso-enterprise.csh</computeroutput> - csh, tcsh, and related shells</listitem>
            </itemizedlist>
          </listitem>
          <listitem>Execute the command:  oplmgr +stop</listitem>
          <listitem>Retrieve your new Virtuoso license file from an email or <link linkend="oplmngrlflb">ODS Briefcase</link>. Use binary-mode ftp to transfer the new license to the Unix box, if required.</listitem>
          <listitem>Place the new license in the bin sub-directory of the Virtuoso installation.</listitem>
          <listitem>Set and export an <computeroutput>OPL_LICENSE_DIR</computeroutput> environment variable that passes the path to the directory that contains your Virtuoso license file, e.g
            <itemizedlist>
              <listitem><computeroutput>export OPL_LICENSE_DIR="/opt/virtuoso/bin/"</computeroutput></listitem>
              <listitem><computeroutput>OPL_LICENSE_DIR="/opt/virtuoso/bin/" ; export OPL_LICENSE_DIR</computeroutput></listitem>
            </itemizedlist>
          </listitem>
          <listitem>Execute the command: <computeroutput>oplmgr +start</computeroutput></listitem>
        </orderedlist>
      </sect4>
      <sect4 id="oplmngrlflb"><title>Retrieve OpenLink Licenses from Your <link linkend="oplmngrlflb">ODS Briefcase</link></title>
        <para>OpenLink's registered users receive an automatic OpenLink Data Spaces (ODS) account on
the My OpenLink home page. This account allows registered users to experience and explore OpenLink's
Virtuoso Universal Cilent applications.It also provides a convenient storage mechanism for OpenLink
commercial and evaluation license keys.
        </para>
        <para>This page shows you how to access licenses that reside in your <link linkend="oplmngrlflb">ODS Briefcase</link>. A second
15 Day evaluation license is automatically copied to the Briefcase, when you download our software and
receive your first 15 Day key. You may access the Briefcase by clicking on the link that appears in the
email that contains the first license. Alternatively, you may identify the ODS url by logging into the
OpenLink site.
        </para>
        <para>The following instructions will allow you to access your <link linkend="oplmngrlflb">ODS Briefcase</link> via the OpenLink
Web site.
        </para>
        <orderedlist>
          <listitem>Click the Login link that appears on the OpenLink Web page.
            <figure id="rdfinsertwebdav1" float="1">
	      <title>ODS Briefcase</title>
	      <graphic fileref="ui/ODSA.png"/>
            </figure>
          </listitem>
          <listitem>Click the "Login Here" button that appears in the Registered Users box.
            <figure id="rdfinsertwebdav1" float="1">
	      <title>ODS Briefcase</title>
	      <graphic fileref="ui/ODSB.png"/>
            </figure>
          </listitem>
          <listitem>Click the "Check my profile" link that appears in the Welcome box.
            <figure id="rdfinsertwebdav1" float="1">
	      <title>ODS Briefcase</title>
	      <graphic fileref="ui/ODSC.png"/>
            </figure>
          </listitem>
          <listitem>Click the ODS Service URL that appears in the lower right hand corner of the My Details dialog.
            <figure id="rdfinsertwebdav1" float="1">
	      <title>ODS Briefcase</title>
	      <graphic fileref="ui/ODS3.png"/>
            </figure>
          </listitem>
          <listitem>Allow the My OpenLink Web page to load in a Web browser.
            <figure id="rdfinsertwebdav1" float="1">
	      <title>ODS Briefcase</title>
	      <graphic fileref="ui/ODS4.png"/>
            </figure>
          </listitem>
          <listitem>Login to your OpenLink Data Space using your OpenLink login.
            <figure id="rdfinsertwebdav1" float="1">
	      <title>ODS Briefcase</title>
	      <graphic fileref="ui/ODS5.png"/>
            </figure>
          </listitem>
          <listitem>Click the Briefcase link that appears in the ODS menu bar at the top of the page.
            <figure id="rdfinsertwebdav1" float="1">
	      <title>ODS Briefcase</title>
	      <graphic fileref="ui/ODS6.png"/>
            </figure>
          </listitem>
          <listitem>Your license will appear as a Resource Item under the Briefcase Summary.
            <figure id="rdfinsertwebdav1" float="1">
	      <title>ODS Briefcase</title>
	      <graphic fileref="ui/ODS7.png"/>
            </figure>
          </listitem>
        </orderedlist>
        <para>Click the license link to download your license. Provide your OpenLink username and
password if prompted for a DAV login.
        </para>
      </sect4>
    </sect3>
    <sect3 id="oplmngrlflp"><title>License Preservation</title>
     <para>Users may choose to preserve the existing license file when applying a new license file. This facilitates a rollback to the original file, if the replacement file is problematic.</para>
      <sect4 id="oplmngrlflp"><title>Mac OS X</title>
        <itemizedlist>
          <listitem>Use StuffIt or a similar utility to store the file in a compressed archive.</listitem>
          <listitem>Rename the file, e.g., from <computeroutput>virtuoso.lic</computeroutput> to <computeroutput>virtuoso.lic-old</computeroutput></listitem>
        </itemizedlist>
      </sect4>
      <sect4 id="oplmngrlflp"><title>Windows</title>
        <para>Use WinZip or a similar utility to copy your license file to a .zip archive.</para>
      </sect4>
      <sect4 id="oplmngrlflp"><title>Unix-like OS (AIX, HP-UX, Linux, Solaris, etc.)</title>
        <para>Use tar or gzip to copy your license file into an archive. For example: <computeroutput>tar cvzf virtuoso-lic.tgz virtuoso.lic</computeroutput></para>
      </sect4>
    </sect3>
    <sect3 id="oplmngrlflr"><title>License Removal</title>
      <para>Users may choose to remove expired or deprecated license files altogether to ensure the uptake of a new license file.</para>
      <sect4 id="oplmngrlflr"><title>Mac OS X</title>
        <orderedlist>
          <listitem>Shutdown your OpenLink License Manager</listitem>
          <listitem>Click the Search icon.</listitem>
          <listitem>Type your license name into the search box. For example: virtuoso.lic</listitem>
          <listitem>Drag the license from the search results onto the trash icon.</listitem>
          <listitem>Expand the Finder menu.</listitem>
          <listitem>Click Empty Trash.</listitem>
        </orderedlist>
      </sect4>
      <sect4 id="oplmngrlflr"><title>Windows</title>
        <orderedlist>
          <listitem>Launch the <emphasis>Services</emphasis> Control Panel (may be in the <emphasis>Administrative Tools</emphasis> sub-folder).</listitem>
          <listitem>Locate and select the <emphasis>OpenLink Virtuoso</emphasis> service.</listitem>
          <listitem>Click the <emphasis>Stop</emphasis> icon.</listitem>
          <listitem>Locate and select the <emphasis>OpenLink License Manager</emphasis> service.</listitem>
          <listitem>Click the <emphasis>Stop</emphasis> icon.</listitem>
          <listitem>Launch the Windows Search utility, from the Start menu.</listitem>
          <listitem>Search for all files with the name <computeroutput>virtuoso.lic.</computeroutput></listitem>
          <listitem>Drag all found licenses to the Recycle Bin.</listitem>
          <listitem>Empty the Recycle Bin</listitem>
        </orderedlist>
      </sect4>
      <sect4 id="oplmngrlflr"><title>Unix-like OS (AIX, HP-UX, Linux, Solaris, etc.)</title>
        <orderedlist>
          <listitem>Login to the Unix or Linux operating system.</listitem>
          <listitem>Use the find command to locate relevant license files, and check their permissions and ownership.
<programlisting><![CDATA[
bash-2.03$ find / -name virtuoso.lic -exec ls -l {} \;
-rw-r--r--   1 virtuoso other        645 Mar 11 08:06 /usr/virtuoso/bin/virtuoso.lic
bash-2.03$
]]></programlisting>
          </listitem>
          <listitem>Use the rm command to remove the license file(s).
<programlisting><![CDATA[
bash-2.03$ rm /usr/virtuoso/bin/virtuoso.lic
]]></programlisting>
          </listitem>
          <listitem>
            <para>If the file permissions and ownership require, you can use sudo - </para>
<programlisting><![CDATA[
bash-2.03$ sudo rm /usr/virtuoso/bin/virtuoso.lic
Password:
bash-2.03$ ls /usr/virtuoso/bin/virtuoso.lic
bash-2.03$
]]></programlisting>
            <para> - or su to the appropriate user or group - </para>
<programlisting><![CDATA[
bash-2.03$ su virtuoso
Password:
bash-2.03$ rm /usr/virtuoso/bin/virtuoso.lic
bash-2.03$ ls /usr/virtuoso/bin/virtuoso.lic
bash-2.03$
]]></programlisting>
          </listitem>
        </orderedlist>
      </sect4>
    </sect3>
  </sect2>
  <sect2 id="oplmngrlm"><title>License Manager</title>
    <sect3 id="oplmngrlmml"><title>Monitor License Consumption</title>
      <para>OpenLink's License Manager technology provides a sophisticated and easy to use License
statistics and monitoring facility. This page introduces you to that facility and provides alternative
techniques for versions of the software that do not contain it.
      </para>
      <orderedlist>
        <listitem>Launch the Virtuoso Web interface.</listitem>
        <listitem>Click the <emphasis>Conductor</emphasis> link.</listitem>
        <listitem>Login with your Virtuoso dba account.</listitem>
        <listitem>Click the <emphasis>System Admin</emphasis> tab.</listitem>
        <listitem>Locate the <emphasis>License</emphasis> section to review the terms of your Virtuoso license.</listitem>
        <listitem>Locate the <emphasis>Clients</emphasis> section to review open connections that consume Virtuoso license points.</listitem>
      </orderedlist>
    </sect3>
    <sect3 id="oplmngrlmsl"><title>Start the License Manager Process</title>
       <sect4 id="oplmngrlmslm"><title>Mac OS X</title>
          <orderedlist>
            <listitem>Launch <computeroutput> Terminal.app  (/Applications/Utilities/) </computeroutput></listitem>
            <listitem>Execute the command <computeroutput>cd "/Library/Application Support/openlink/bin/"</computeroutput></listitem>
            <listitem>Execute the command <computeroutput>oplmgr +start</computeroutput></listitem>
          </orderedlist>
       </sect4>
       <sect4 id="oplmngrlmslw"><title>Windows</title>
          <orderedlist>
            <listitem>Launch the <emphasis>Services</emphasis> Control Panel (may be in the <emphasis>Administrative Tools</emphasis> sub-folder).</listitem>
            <listitem>Locate and select the <emphasis>OpenLink Virtuoso</emphasis> service.</listitem>
            <listitem>Click the <emphasis>Start</emphasis> icon.</listitem>
          </orderedlist>
       </sect4>
       <sect4 id="oplmngrlmslu"><title>Unix-like OS (AIX, HP-UX, Linux, Solaris, etc.)</title>
        <orderedlist>
          <listitem>Open a Unix terminal.</listitem>
          <listitem><computeroutput>cd</computeroutput> into the root of your Virtuoso installation.</listitem>
          <listitem>Use one of the following commands to set Virtuoso-related environment variables. (Note that they do, and must, begin with dot-space-dot-slash.)
            <itemizedlist>
              <listitem><computeroutput>. ./virtuoso-enterprise.sh</computeroutput> - bash, bsh, ksh, and related shells</listitem>
              <listitem><computeroutput>. ./virtuoso-enterprise.csh</computeroutput> - csh, tcsh, and related shells</listitem>
            </itemizedlist>
          </listitem>
          <listitem>Execute the command: <computeroutput>oplmgr +start</computeroutput></listitem>
        </orderedlist>
       </sect4>
       <para><emphasis>Note</emphasis>: OpenLink recommends that you create an <computeroutput>/etc/init.d/</computeroutput>
script that sets the environment and runs <computeroutput>oplmgr +start</computeroutput> at boot time.
       </para>
    </sect3>
    <sect3 id="oplmngrlmlp"><title>Stop the License Manager Process</title>
       <sect4 id="oplmngrlmlpm"><title>Mac OS X</title>
          <orderedlist>
            <listitem>Launch <computeroutput> Terminal.app  (/Applications/Utilities/) </computeroutput></listitem>
            <listitem>Execute the command <computeroutput>cd "/Library/Application Support/openlink/bin/"</computeroutput></listitem>
            <listitem>Execute the command <computeroutput>oplmgr +stop</computeroutput></listitem>
          </orderedlist>
       </sect4>
       <sect4 id="oplmngrlmlpw"><title>Windows</title>
          <orderedlist>
            <listitem>Launch the <emphasis>Services</emphasis> Control Panel (may be in the <emphasis>Administrative Tools</emphasis> sub-folder).</listitem>
            <listitem>Locate and select the <emphasis>OpenLink License Manager service</emphasis>.</listitem>
            <listitem>Click the <emphasis>Stop</emphasis> icon.</listitem>
          </orderedlist>
       </sect4>
       <sect4 id="oplmngrlmlpu"><title>Unix-like OS (AIX, HP-UX, Linux, Solaris, etc.)</title>
          <orderedlist>
            <listitem>Open a Unix terminal.</listitem>
            <listitem><computeroutput>cd</computeroutput> into the root of your Virtuoso installation.</listitem>
            <listitem>Use one of the following commands to set Virtuoso-related environment variables. (Note that they do, and must, begin with dot-space-dot-slash.)
              <itemizedlist>
                <listitem><computeroutput>. ./virtuoso-enterprise.sh</computeroutput> - bash, bsh, ksh, and related shells</listitem>
                <listitem><computeroutput>. ./virtuoso-enterprise.csh</computeroutput> - csh, tcsh, and related shells</listitem>
              </itemizedlist>
            </listitem>
            <listitem>Execute the command:  oplmgr +stop</listitem>
          </orderedlist>
       </sect4>
    </sect3>
    <sect3 id="oplmngrlmrl"><title>Reinitialize the License Manager Process</title>
       <sect4 id="oplmngrlmrlm"><title>Mac OS X</title>
          <orderedlist>
            <listitem>Launch <computeroutput> Terminal.app  (/Applications/Utilities/) </computeroutput></listitem>
            <listitem>Execute the command <computeroutput>cd "/Library/Application Support/openlink/bin/"</computeroutput></listitem>
            <listitem>Execute the command <computeroutput>oplmgr +reload</computeroutput></listitem>
          </orderedlist>
       </sect4>
       <sect4 id="oplmngrlmrlw"><title>Windows</title>
          <orderedlist>
            <listitem>Launch the <emphasis>Services</emphasis> Control Panel (may be in the <emphasis>Administrative Tools</emphasis> sub-folder).</listitem>
            <listitem>Locate and select the <emphasis>OpenLink License Manager service</emphasis>.</listitem>
            <listitem>Click the <emphasis>Restart</emphasis> icon.</listitem>
          </orderedlist>
       </sect4>
       <sect4 id="oplmngrlmrlu"><title>Unix-like OS (AIX, HP-UX, Linux, Solaris, etc.)</title>
          <orderedlist>
            <listitem>Open a Unix terminal.</listitem>
            <listitem><computeroutput>cd</computeroutput> into the root of your Virtuoso installation.</listitem>
            <listitem>Use one of the following commands to set Virtuoso-related environment variables. (Note that they do, and must, begin with dot-space-dot-slash.)
              <itemizedlist>
                <listitem><computeroutput>. ./virtuoso-enterprise.sh</computeroutput> - bash, bsh, ksh, and related shells</listitem>
                <listitem><computeroutput>. ./virtuoso-enterprise.csh</computeroutput> - csh, tcsh, and related shells</listitem>
              </itemizedlist>
            </listitem>
            <listitem>Execute the command: oplmgr +reload</listitem>
          </orderedlist>
       </sect4>
    </sect3>
    <sect3 id="oplmngrlmau"><title>Additional Usage Notes</title>
       <para>The license manager takes several command-line arguments, as revealed by its "usage" output (produced by any unrecognized argument) -- </para>
<programlisting><![CDATA[

      bash$ oplmgr --help
      OpenLink License Manager
      Version 1.2.2 as of Thu Feb 15 2007 (Release 6.0 cvsid 00084).
      Compiled for Linux 2.4.20-46.9.legacysmp (i686-generic-linux-glibc23-32)
      Copyright (C) OpenLink Software.

      Usage:
      oplmgr [-shrutp] [+start] [+stop] [+reload] [+user arg] [+chroot arg]
      [+pidfile arg]
      +start     start the license manager
      +stop      stop the license manager
      +reload    force a configuration reload
      +user      run as the specified user
      +chroot    perform a chroot to the specified directory
      +pidfile   pid file to use for server operation

]]></programlisting>
    </sect3>
  </sect2>
  <sect2 id="oplmngrdlp"><title>Debugging License Problems</title>
       <para>Virtuoso license problems are easy to debug. The following information provides a
conceptual framework and troubleshooting tips suitable for all licensing problems.
       </para>
    <sect3 id="oplmngrdlpil"><title>Identifying License Problems</title>
       <para>License problems occur when users attempt to apply them to products or when they hit a
ceiling associated with concurrent usage. Most license errors are explicit and include text that
states that a license is invalid, expired, or exceeded. Problems associated with performance or
stability problems that do not produce license related errors are not likely to be caused by licenses.
There is no scenario in which use of an evaluation key would contribute to limited functionality.
OpenLink's products are fully functional regardless of the license key applied. The license key simply
dictates the length of time for which a product may be used.
       </para>
    </sect3>
    <sect3 id="oplmngrdlpsl"><title>Source of License Problems</title>
       <para>Licenses problems appear under the following circumstances:</para>
       <itemizedlist>
         <listitem>A license file is ftp'd in ASCII.</listitem>
         <listitem>The license covers a different OpenLink product.</listitem>
         <listitem>The license covers a different OpenLink release.</listitem>
         <listitem>A machine has more physical Processor cores than allotted for by the license.</listitem>
         <listitem>The license can not be found.</listitem>
         <listitem>The wrong license is being found.</listitem>
         <listitem>You did not perform the appropriate steps to register the license.</listitem>
         <listitem>The License Manager process needs to be restarted.</listitem>
         <listitem>The license is inadequate for your level of concurrent activity</listitem>
       </itemizedlist>
    </sect3>
    <sect3 id="oplmngrdlptl"><title>Troubleshooting License Problems</title>
       <para>Use the following tips to resolve your licensing tips or supply OpenLink Technical Services with your findings:</para>
       <itemizedlist>
         <listitem>FTP all licenses (virtuoso.lic) in binary mode.</listitem>
         <listitem>Review the terms of the email that contained the license.</listitem>
         <listitem>Ensure that the license that you have received is for Virtuoso Universal Server and not a data access provider or driver.</listitem>
         <listitem>Compare the Virtuoso version on your machine with the version covered by the license key.</listitem>
         <listitem>Identify the number of physical Processor cores on the box that hosts the license and ensure those cores are covered by the license key.</listitem>
         <listitem>Use OpenLink's licensing guidelines to ensure that the license is placed in the appropriate location on the target machine.</listitem>
         <listitem>Use the host machine's search utilities to ensure that expired or deprecated license files are removed from the host machine and deleted from the trash.</listitem>
         <listitem>Use OpenLink's licensing guidelines to ensure that you have performed the license application procedure using the correct steps in the appropriate order.</listitem>
         <listitem>Use the host monitoring utilities to ensure that applicable processes have been restarted as detailed in OpenLink's licensing guidelines.</listitem>
       </itemizedlist>
    </sect3>
  </sect2>
</sect1>
  <sect1 id="installvsgrid"><title>Virtuoso ADO.Net Data Grid Form Application</title>
  <para>This section details the steps required to create a simple Visual Studio 2008 Windows Form
application with associated DataGridView control for displaying data in selected tables from a Virtuoso
database.</para>
<orderedlist>
  <listitem>Launch the Visual Studio 2008 SP1 IDE.
    <figure id="insg1" float="1">
      <title>Visual Studio</title>
      <graphic fileref="ui/insg1.png"/>
    </figure>
  </listitem>
  <listitem>Create a Web Application project by going to the File menu in Visual Studio and choosing New Project.
  </listitem>
  <listitem>When the New Project window appears, choose either Visual Basic or Visual C# as the programming language.
  </listitem>
  <listitem>Within the language category, click on Windows and select Windows Form Application from the right-hand panel.
  </listitem>
  <listitem>Choose a name for the project, for example VirtuosoDataGridApp, and click OK.
    <figure id="insg5" float="1">
      <title>name for the project</title>
      <graphic fileref="ui/insg5.png"/>
    </figure>
  </listitem>
  <listitem>From the Data, menu select the Show Data Sources menu item to display a list of available Data sources.
    <figure id="insg6" float="1">
      <title>Show Data Sources</title>
      <graphic fileref="ui/insg6.png"/>
    </figure>
  </listitem>
  <listitem>Click on the Add New Data Source link to add a new data source.
    <figure id="insg7" float="1">
      <title>Add New Data Source</title>
      <graphic fileref="ui/insg7.png"/>
    </figure>
  </listitem>
  <listitem>In the Data Source Configuration Wizard dialog  Choose Data Source Type page, select the Database data source type and click Next.
    <figure id="insg8" float="1">
      <title>Data Source Configuration Wizard</title>
      <graphic fileref="ui/insg8.png"/>
    </figure>
  </listitem>
  <listitem>In the Data Source Configuration Wizard dialog Choose your Data Connection page, select the New Connection button.
    <figure id="insg9" float="1">
      <title>Data Connection page</title>
      <graphic fileref="ui/insg9.png"/>
    </figure>
  </listitem>
  <listitem>In the Choose Data Source dialog, select OpenLink Virtuoso Data Source from the list and click Continue.
    <figure id="insg10" float="1">
      <title>OpenLink Virtuoso Data Source</title>
      <graphic fileref="ui/insg10.png"/>
    </figure>
  </listitem>
  <listitem>In the Add Connection dialog, specify the hostname, portno, username, and password
for the target Virtuoso Server and check the Save Password check box.
    <figure id="insg11" float="1">
      <title>Add Connection dialog</title>
      <graphic fileref="ui/insg11.png"/>
    </figure>
  </listitem>
  <listitem>Select the Select Database From List radio button and choose School from the drop down list
of available databases.
    <figure id="insg12" float="1">
      <title>Select Database From List</title>
      <graphic fileref="ui/insg12.png"/>
    </figure>
  </listitem>
  <listitem>Click the Test Connection button to verify the connection is successful and then
click OK to add the connection.
    <figure id="insg13" float="1">
      <title>Test Connection</title>
      <graphic fileref="ui/insg13.png"/>
    </figure>
  </listitem>
  <listitem>Select the  Yes, include sensitive data in the connect string radio button and click Next to continue.
    <figure id="insg14" float="1">
      <title>connect string</title>
      <graphic fileref="ui/insg14.png"/>
    </figure>
  </listitem>
  <listitem>In the Choose your Database Objects dialog select the table and columns to be queried, the shippers table is used in this example.
    <figure id="insg15" float="1">
      <title>Choose your Database Objects</title>
      <graphic fileref="ui/insg15.png"/>
    </figure>
  </listitem>
  <listitem>A DataSet for the shippers database object is created
    <figure id="insg16" float="1">
      <title>shippers database</title>
      <graphic fileref="ui/insg16.png"/>
    </figure>
  </listitem>
  <listitem>From the drop down list box next to the Shippers table ensure the DataGridView item is selected
    <figure id="insg17" float="1">
      <title>DataGridView</title>
      <graphic fileref="ui/insg17.png"/>
    </figure>
  </listitem>
  <listitem>Drag the Shippers DataSet item onto the Form to create a scrollable and editable association of the Shippers table object with the Data Grid View automatically.
    <figure id="insg18" float="1">
      <title>Drag</title>
      <graphic fileref="ui/insg18.png"/>
    </figure>
  </listitem>
  <listitem>From the Debug Menu select the Start Debugging menu item to run the application.
    <figure id="insg19" float="1">
      <title>Debug</title>
      <graphic fileref="ui/insg19.png"/>
    </figure>
  </listitem>
  <listitem>The data in the Shippers table will be displayed in the DataGrid application created.
    <figure id="insg20" float="1">
      <title>DataGrid</title>
      <graphic fileref="ui/insg20.png"/>
    </figure>
  </listitem>
  <listitem>A new row can be inserted (updated or deleted) as indicated for the new DHL record inserted below and the  save button clicked to save the change to the database.
    <figure id="insg21" float="1">
      <title>new row</title>
      <graphic fileref="ui/insg21.png"/>
    </figure>
  </listitem>
  <listitem>The Virtuoso Interactive SQL tab of the Conductor can be used to run the query select * from Demo..Shippers.
    <figure id="insg22" float="1">
      <title>Interactive SQL tab</title>
      <graphic fileref="ui/insg22.png"/>
    </figure>
  </listitem>
  <listitem>To verify the change has been successfully made in the database.
    <figure id="insg23" float="1">
      <title>verify</title>
      <graphic fileref="ui/insg23.png"/>
    </figure>
  </listitem>
</orderedlist>
  <para>The task is now complete.</para>
</sect1>
  <sect1 id="installvsent"><title>Using Visual Studio 2008 to Build an Entity Frameworks based Windows Form Application</title>
    <formalpara><title>Virtuoso Entity Framework School DB Windows Form Application</title></formalpara>
    <para>This section demonstrates how Visual Studio 2008 can be used to generate mapping files
for an Entity Data Model (EDM), based on a 1:1 mapping to tables in the School database. This will be
done by creating a Windows Forms application in Visual Studio, create queries that access data in the
School model, bind the query results to display controls to show the results of the queries, and then
make updates to objects and persist the changes to the database.</para>
      <sect2 id="installvsentprereq">
        <title>Pre-requisites</title>
        <para>In order to create an Entity Framework Application in your own environment you will need:</para>
        <orderedlist>
          <listitem>Microsoft Visual Studio 2008 SP1, the ADO.NET Entity Framework runtime and associated tools are included
          	in Visual Studio 2008 SP1.</listitem>
          <listitem>A running Virtuoso Universal Server instance.</listitem>
        </orderedlist>
      </sect2>
      <sect2 id="installvsentcreatedb">
        <title>Create the School database and schema</title>
        <orderedlist>
          <listitem>Download the <ulink url="http://download.openlinksw.com/packages/5.0/virtuoso/schools_db_dav.vad">Schools Database</ulink> VAD (schools_db_dav.vad) package.</listitem>
          <listitem>Navigate to the <emphasis>System Admin -> Packages</emphasis> tab of the Virtuoso Conductor.
            <figure id="uado1" float="1">
              <title>Conductor Packages</title>
              <graphic fileref="ui/uado1.png"/>
            </figure>
          </listitem>
          <listitem>Scroll down to the <emphasis>Install Package</emphasis> section of the tab, use the
<emphasis>Upload Package</emphasis> option <emphasis>Browse</emphasis> button to locate the
schools_db_dav.vad package and click <emphasis>proceed</emphasis>.
             <figure id="uado2" float="1">
               <title>Install package</title>
               <graphic fileref="ui/uado2.png"/>
             </figure>
           </listitem>
           <listitem>Click the <emphasis>Proceed</emphasis> button to begin the installation process.
             <figure id="uado3" float="1">
               <title>Install package.</title>
               <graphic fileref="ui/uado3.png"/>
             </figure>
           </listitem>
           <listitem>Once complete return to the <emphasis>Packages</emphasis> tab and scroll down to confirm the *schools_db*
           package is listed as installed.
             <figure id="uado4" float="1">
               <title>Install package</title>
               <graphic fileref="ui/uado4.png"/>
             </figure>
           </listitem>
        </orderedlist>
        <para><emphasis>Create the Course Manager application using Visual Studio</emphasis></para>
        <orderedlist>
          <listitem>Launch the Visual Studio 2008 SP1 IDE.
            <figure id="uados1" float="1">
              <title>Visual Studio 2008 SP1 IDE</title>
              <graphic fileref="ui/uados1.png"/>
            </figure>
          </listitem>
          <listitem>On the <emphasis>File menu</emphasis> click <emphasis>New Project</emphasis>.
          </listitem>
          <listitem>Choose either <emphasis>Visual Basic</emphasis> or <emphasis>Visual C#</emphasis> in the
<emphasis>Project Types</emphasis> pane.
          </listitem>
          <listitem>Select <emphasis>Windows Forms Application</emphasis> in the
<emphasis>Templates</emphasis> pane.
          </listitem>
          <listitem>Enter <emphasis>CourseManager</emphasis> for the project name, and then
click <emphasis>OK</emphasis>.
            <figure id="uado5" float="1">
              <title>Create project</title>
              <graphic fileref="ui/uado5.png"/>
            </figure>
          </listitem>
        </orderedlist>
        <para><emphasis>Create the Course Viewer form</emphasis></para>
        <orderedlist>
          <listitem>In the <emphasis>CourseManager</emphasis> project, select the default form (Form1).
          </listitem>
          <listitem>In the <emphasis>File Properties</emphasis> pane, change the File Name to
<emphasis>CourseViewer.vb</emphasis> or <emphasis>CourseViewer.cs</emphasis>.
          </listitem>
          <listitem>In <emphasis>Solution Explorer</emphasis>, double-click
<emphasis>CourseViewer.vb</emphasis> or <emphasis>CourseViewer.cs</emphasis> to open the form.
            <figure id="uado6" float="1">
              <title>CourseViewer.vb</title>
              <graphic fileref="ui/uado6.png"/>
            </figure>
          </listitem>
          <listitem>In the <emphasis>Toolbox</emphasis>, expand <emphasis>Common Controls</emphasis>,
drag the <emphasis>ComboBox</emphasis> control to the form, and change the name of the control to
<emphasis>departmentList</emphasis>.
          </listitem>
          <listitem>In the <emphasis>Toolbox</emphasis>, drag the <emphasis>Button</emphasis>
control to the form, change the <emphasis>Name</emphasis> of the control to <emphasis>closeForm</emphasis>,
and change the <emphasis>Text value</emphasis> to <emphasis>Close</emphasis>.
          </listitem>
          <listitem>In the <emphasis>Toolbox</emphasis>, expand <emphasis>Data</emphasis>, drag the
<emphasis>DataGridView</emphasis> control to the form, and change the <emphasis>Name</emphasis> of
the control to <emphasis>courseGridView</emphasis>.
            <figure id="uado7" float="1">
              <title>DataGridView</title>
              <graphic fileref="ui/uado7.png"/>
            </figure>
          </listitem>Double-click the <emphasis>closeForm</emphasis> button control. This opens
the code page for the form and creates the closeForm_Click event handler method.
          <listitem>In the <emphasis>closeForm_Click</emphasis> event handler method, type the following code that closes the form:
<programlisting><![CDATA[
Visual Basic

' Close the form.
Me.Close()

C#

// Close the form.
this.Close();
]]></programlisting>
            </listitem>
          </orderedlist>
        </sect2>
        <sect2 id="installvsentgenmodel">
          <title>Generating the School Entity Data Mode</title>
          <para><emphasis>Add the ADO.NET Entity Data Model item template</emphasis></para>
          <orderedlist>
            <listitem>Select the CourseManager project in Solution Explorer, right-click, point to Add, and then click New Item.</listitem>
            <listitem>Select ADO.NET Entity Data Model in the Templates pane.</listitem>
            <listitem>Type School.edmx for the model name and click Add. The opening page of the Entity Data Model Wizard is displayed.
              <figure id="uado8" float="1">
                <title>School.edmx</title>
                <graphic fileref="ui/uado8.png"/>
              </figure>
            </listitem>
          </orderedlist>
          <para><emphasis>Generate the EDM</emphasis></para>
          <orderedlist>
            <listitem>Select <emphasis>Generate from database</emphasis> in the
<emphasis>Choose Model Contents dialog box</emphasis>. Then click <emphasis>Next</emphasis>.
              <figure id="uado9" float="1">
                <title>Model Contents</title>
                <graphic fileref="ui/uado9.png"/>
              </figure>
            </listitem>
            <listitem>Click the <emphasis>New Connection</emphasis> button.
              <figure id="uado10" float="1">
                <title>New Connection</title>
                <graphic fileref="ui/uado10.png"/>
              </figure>
            </listitem>
            <listitem>Choose the OpenLink <emphasis>Virtuoso Data Source</emphasis> and click
<emphasis>Continue</emphasis>.
              <figure id="uado11" float="1">
                <title>Virtuoso Data Source</title>
                <graphic fileref="ui/uado11.png"/>
              </figure>
            </listitem>
            <listitem>In the <emphasis>Connection Properties</emphasis> dialog specify the
<emphasis>hostname, portno, username and password</emphasis> for the target Virtuoso Server and click the
<emphasis>Advanced</emphasis> button.
             <figure id="uado12" float="1">
               <title>Connection Properties</title>
               <graphic fileref="ui/uado12.png"/>
             </figure>
           </listitem>
           <listitem>In the <emphasis>Advanced Properties</emphasis> dialog set the
<emphasis>Database parameter</emphasis> to <emphasis>School</emphasis> and click OK.
             <figure id="uado13" float="1">
               <title>Advanced Properties</title>
               <graphic fileref="ui/uado13.png"/>
             </figure>
           </listitem>
           <listitem>Press the <emphasis>Test Connection</emphasis> dialog to verify the database is accessible.
             <figure id="uado14" float="1">
               <title>Test Connection</title>
               <graphic fileref="ui/uado14.png"/>
             </figure>
           </listitem>
           <listitem>Set the <emphasis>entity connect string name</emphasis> to
<emphasis>SchoolEntities</emphasis> and click <emphasis>Next</emphasis>.
             <figure id="uado15" float="1">
               <title>entity connect string name</title>
               <graphic fileref="ui/uado15.png"/>
             </figure>
           </listitem>
           <listitem>In the <emphasis>Choose your Database Objects</emphasis> page select the
<emphasis>Tables</emphasis> check box to select all table in the <emphasis>School database</emphasis>
for addition to the EDM, set the <emphasis>Model Namespace</emphasis> to <emphasis>SchoolModel</emphasis>
and click <emphasis>Finish</emphasis>.
            <figure id="uado16" float="1">
              <title>Database Objects</title>
              <graphic fileref="ui/uado16.png"/>
            </figure>
          </listitem>
        </orderedlist>
        <para><emphasis>View the EDM in the ADO.NET Entity Data Model Designer</emphasis></para>
        <orderedlist>
          <listitem>In the <emphasis>Solution Explorer</emphasis>, double-click the <emphasis>School.edmx</emphasis>
          file. This displays the School model in the ADO.NET Entity Data Model Designer window.
            <figure id="uado17" float="1">
              <title>Solution Explorer</title>
              <graphic fileref="ui/uado17.png"/>
            </figure>
          </listitem>
          <listitem>From the <emphasis>View</emphasis> menu, select <emphasis>Other Windows</emphasis>, and then click
          <emphasis>Model Browser</emphasis> to display the <emphasis>Entity Model Browser</emphasis> window.
          </listitem>
          <listitem>Expand the <emphasis>SchoolModel</emphasis> and <emphasis>SchoolModel.Store</emphasis> nodes to view
          conceptual and store definitions, respectively.
            <figure id="uado20" float="1">
              <title>SchoolModel</title>
              <graphic fileref="ui/uado20.png"/>
            </figure>
          </listitem>
          <listitem>From the <emphasis>View menu</emphasis>, select <emphasis>Other Windows</emphasis>, click
          <emphasis>Mapping Details</emphasis>, and then click an entity (Person for example) or association in the Entity Designer.
            </listitem>
            <listitem>This displays the Entity Mapping Details window with information about the object-relational mapping
            	for the selected object.
              <figure id="uado21" float="1">
                <title>View menu</title>
                <graphic fileref="ui/uado21.png"/>
              </figure>
            </listitem>
          </orderedlist>
        </sect2>
        <sect2 id="installvsentqueryentity">
          <title>Querying Entities and Associations</title>
          <para>This section creates strongly-typed queries against the CLR objects that represent entities and associations
          	in the School model, and bind display controls to the object collections returned from these queries.</para>
          <para><emphasis>Query the departments in the School database</emphasis></para>
          <orderedlist>
            <listitem>At the beginning of the code file for the <emphasis>CourseViewer</emphasis> form,
add the following <emphasis>using</emphasis> (C#) or <emphasis>Imports</emphasis> (Visual Basic) statements to reference the
model created from the School database and the entity namespace.
<programlisting><![CDATA[
Visual Basic

Imports System.Data.Objects
Imports System.Data.Objects.DataClasses

C#

using System.Data.Objects;
using System.Data.Objects.DataClasses;
]]></programlisting>
            </listitem>
            <listitem>At the top of the partial class definition for the <emphasis>CourseViewer</emphasis>
form, add the following code that creates an <emphasis>ObjectContext</emphasis> instance.
<programlisting><![CDATA[
Visual Basic

' Create an ObjectContext instance based on SchoolEntity.
Private schoolContext As SchoolEntities

C#

// Create an ObjectContext instance based on SchoolEntity.
private SchoolEntities schoolContext;
]]></programlisting>
            </listitem>
            <listitem>In the <emphasis>CourseViewer</emphasis> form designer, double-click
the <emphasis>CourseViewer</emphasis> form. This opens the code page for the form and creates the
<emphasis>courseViewer _Load</emphasis> event handler method.</listitem>
            <listitem>In the <emphasis>courseViewer _Load</emphasis> event handler method, copy
and paste the following code that defines the <emphasis>DataGridView</emphasis>, executes a query
that returns a collection of departments (ordered by <emphasis>Name</emphasis>), and binds the
collection of <emphasis>Department</emphasis> objects to the departmentList control.
<programlisting><![CDATA[
Visual Basic

' Initialize the ObjectContext.
schoolContext = New SchoolEntities()

' Define a query that returns all Department objects and related
' Course objects, ordered by name.
Dim departmentQuery As ObjectQuery(Of Department) = _
    schoolContext.Department.Include("Course").OrderBy("it.Name")

Try
    ' Bind the ComboBox control to the query, which is
    ' executed during data binding.
    Me.departmentList.DisplayMember = "Name"
    Me.departmentList.DataSource = departmentQuery
Catch ex As Exception
    MessageBox.Show(ex.Message)
End Try

C#

// Initialize the ObjectContext.
schoolContext = new SchoolEntities();

// Define a query that returns all Department objects and related
// Course objects, ordered by name.
ObjectQuery<Department> departmentQuery =
    schoolContext.Department.Include("Course").OrderBy("it.Name");

try
{
    // Bind the ComboBox control to the query, which is
    // executed during data binding.
    this.departmentList.DisplayMember = "Name";
    this.departmentList.DataSource = departmentQuery;
}
catch (Exception ex)
{
    MessageBox.Show(ex.Message);
}
]]></programlisting>
          </listitem>
        </orderedlist>
        <para><emphasis>Display courses for the selected department</emphasis></para>
        <orderedlist>
          <listitem>In the <emphasis>CourseViewer</emphasis> form designer, double-click the <emphasis>departmentList</emphasis>
          control. This creates the <emphasis>departmentList_SelectedIndexChanged</emphasis> event handler method.</listitem>
          <listitem>Paste the following code that loads the courses that are related to the selected department.
<programlisting><![CDATA[
Visual Basic

Try
    ' Get the object for the selected department.
    Dim department As Department = _
        CType(Me.departmentList.SelectedItem, Department)

    ' Bind the grid view to the collection of Course objects
    ' that are related to the selected Department object.
    courseGridView.DataSource = department.Course

    ' Hide the columns that are bound to the navigation properties on Course.
    courseGridView.Columns("Department").Visible = False
    courseGridView.Columns("CourseGrade").Visible = False
    courseGridView.Columns("OnlineCourse").Visible = False
    courseGridView.Columns("OnsiteCourse").Visible = False
    courseGridView.Columns("Person").Visible = False

    courseGridView.AutoResizeColumns(DataGridViewAutoSizeColumnsMode.AllCells)
Catch ex As Exception
    MessageBox.Show(ex.Message)
End Try

C#

try
{
    // Get the object for the selected department.
    Department department =
        (Department)this.departmentList.SelectedItem;

    // Bind the grid view to the collection of Course objects
    // that are related to the selected Department object.
    courseGridView.DataSource = department.Course;

    // Hide the columns that are bound to the navigation properties on Course.
    courseGridView.Columns["Department"].Visible = false;
    courseGridView.Columns["CourseGrade"].Visible = false;
    courseGridView.Columns["OnlineCourse"].Visible = false;
    courseGridView.Columns["OnsiteCourse"].Visible = false;
    courseGridView.Columns["Person"].Visible = false;

    courseGridView.AutoResizeColumns(DataGridViewAutoSizeColumnsMode.AllCells);
}
catch (Exception ex)
{
    MessageBox.Show(ex.Message);
}
]]></programlisting>
            </listitem>
          </orderedlist>
        </sect2>
        <sect2 id="installvsentinsertandupdate">
          <title>Inserting and Updating Data</title>
          <para>In this section the changes made to Course objects bound are saved to the DataGridView control to the
          	database and also run the completed Course Manager application.</para>
          <para><emphasis>Save changes made to objects</emphasis></para>
          <orderedlist>
            <listitem>In the <emphasis>Toolbox</emphasis>, expand <emphasis>Common Controls</emphasis>,
drag the <emphasis>Button</emphasis> control to the <emphasis>CourseViewer</emphasis> form designer,
change the <emphasis>name</emphasis> of the control to <emphasis>saveChanges</emphasis>, and change the
<emphasis>Text</emphasis> value to <emphasis>Update</emphasis>.</listitem>
            <listitem>In the <emphasis>CourseViewer</emphasis> form designer, double-click the
<emphasis>saveChanges</emphasis> control. This creates the <emphasis>saveChanges_Click</emphasis> event handler method.
            </listitem>
            <listitem>Paste the following code that saves object changes to the database.
<programlisting><![CDATA[
Visual Basic

Try
    ' Save object changes to the database, display a message,
    ' and refresh the form.
    schoolContext.SaveChanges()
    MessageBox.Show("Changes saved to the database.")
    Me.Refresh()
Catch ex As Exception
    MessageBox.Show(ex.Message)
End Try

C#

try
{
    // Save object changes to the database, display a message,
    // and refresh the form.
    schoolContext.SaveChanges();
    MessageBox.Show("Changes saved to the database.");
    this.Refresh();
}
catch (Exception ex)
{
    MessageBox.Show(ex.Message);
}
]]></programlisting>
            </listitem>
            <listitem>In the <emphasis>closeForm_Click</emphasis> event handler method, type the
following code. This code disposes of the object context before the form is closed.
<programlisting><![CDATA[
Visual Basic

   ' Dispose the object context.
    schoolContext.Dispose()

C#

    // Dispose the object context.
    schoolContext.Dispose();
]]></programlisting>
          </listitem>
        </orderedlist>
        <para><emphasis>Build and run the Class Scheduling application</emphasis></para>
        <orderedlist>
          <listitem>From the <emphasis>Debug</emphasis> menu, select
<emphasis>Start Debugging</emphasis> or <emphasis>Start Without Debugging</emphasis>, to build and
run the application.</listitem>
          <listitem>When the form loads, select a department from the <emphasis>ComboBox</emphasis>
control to display the courses that belong to that department.
          <figure id="uado18" float="1">
            <title>ComboBox</title>
            <graphic fileref="ui/uado18.png"/>
          </figure>
        </listitem>
        <listitem>In the <emphasis>DataGridView</emphasis>, update course information or add a
new course and then click <emphasis>Update</emphasis> to save changes to the database and displays a
message box that declares the number of saved changes.
          <figure id="uado19" float="1">
            <title>DataGridView</title>
            <graphic fileref="ui/uado19.png"/>
          </figure>
        </listitem>
      </orderedlist>
      <para>The process is now complete</para>
    </sect2>
  </sect1>
  <sect1 id="installusado"><title>Using Visual Studio 2008 to Build an ADO.NET Data Services based Application</title>
    <formalpara><title>Using Microsoft ADO.Net Data Services with Virtuoso</title></formalpara>
    <sect2 id="installusadointro">
      <title>Introduction</title>
      <para>The goal of Microsoft ADO.NET Data Services is to enable applications to expose data as a
data service that can be consumed by web clients within corporate networks and across the internet. A data
service is reachable via regular HTTP requests, using standard HTTP verbs such as GET, POST, PUT and DELETE
to perform CRUD operations against the service. The payload format used by the service is controllable by the
application, but all options are simple, open formats such as JSON and Atom/APP.
      </para>
      <para>The use of web-friendly technologies make ADO.NET Data Services ideal as a data back-end
for AJAX-style applications, Rich Interactive Applications and other applications that need to operate
against data that is stored across the web.
      </para>
    </sect2>
    <sect2 id="installusadogetstart">
      <title>Getting Started: Creating Data Services</title>
      <para><emphasis>Pre-requisites</emphasis></para>
      <para>In order to create a data service using ADO.NET Data Services in your own environment you
will need Microsoft Visual Studio 2008 SP1. The ADO.NET Entity Framework runtime and associated tools are
included in Visual Studio 2008 SP1.
      </para>
      <para><emphasis>Selecting a Data Source</emphasis></para>
      <para>The ADO.NET Data Service server framework is comprised of two halves. The top-half is the
runtime itself; this part is "fixed", and it implements URI translation, the Atom/JSON wire formats, the
interaction protocol, etc. This is what makes an ADO.NET Data Service look like an ADO.NET Data Service.
The bottom half is the data-access layer and is pluggable. Communication between layers happens in terms
of the IQueryable interface plus a set of conventions to map CLR graphs into the URI/payload patterns
of ADO.NET Data Services.
      </para>
      <para>The first step in creating an ADO.NET Data Service is to determine the data source that
is to be exposed as a set of REST-based endpoints (ie. select or create a data access layer). For relational
data stored in Microsoft SQL Server or other 3rd Party databases, ADO.NET Data Services currently enables
easily exposing a conceptual model created using the ADO.NET Entity Framework (EF). For all other data
sources (XML section, web service, application logic layer, etc) or to use additional database access
technologies (ex. LINQ to SQL), a mechanism is provided which enables any data source, as per the plug-in
model described above, to be exposed as an ADO.NET Data Service.
      </para>
      <para>To create a data service which exposes a relational database through an Entity Framework
conceptual model see "Creating a Data Service using the ADO.NET Entity Framework". To create a data service
which exposes another data source see "Creating a Data Service from any Data Source".
      </para>
    </sect2>
    <sect2 id="installusadocreateservice">
      <title>Creating a Data Service using the ADO.NET Entity Framework</title>
      <para>ADO.NET Data Services are a specialized form of Windows Communication Foundation services,
and thus can be hosted in various environments. The below example will create an ADO.NET Data Service which
is hosted inside an ASP.NET site. In order to create a data service, you must first create a web project;
you will then need to establish a connection with the database that will be exposed by the service, and
then create the data service itself within the web application. Below is a step-by-step description of
this process.
      </para>
      <para>The following steps can be used for creating a Data Service using the Virtuoso ADO.Net
Provider for accessing the sample Northwind Demo database:
      </para>
      <orderedlist>
        <listitem>Launch the Visual Studio 2008 SP1 IDE.
          <figure id="ados1" float="1">
            <title>Visual Studio 2008 SP1 IDE.</title>
            <graphic fileref="ui/dora1.png"/>
          </figure>
        </listitem>
        <listitem>Create a <emphasis>Web Application</emphasis> project by going to the
<emphasis>File</emphasis> menu in Visual Studio and choosing <emphasis>New Project</emphasis>.
        </listitem>
        <listitem>When the New Project window appears, choose either <emphasis>Visual Basic</emphasis>
or <emphasis>Visual C#</emphasis> as the programming language.
        </listitem>
        <listitem>Within the language category click on <emphasis>Web</emphasis>, and select
        <emphasis>ASP.NET Web Application</emphasis> from the right-hand panel.
        </listitem>
        <listitem>Choose a name for the project, for example <emphasis>VirtuosoDataService</emphasis>,
        and click <emphasis>OK</emphasis>.
          <figure id="ados2" float="1">
            <title>Name project</title>
            <graphic fileref="ui/eora2.png"/>
          </figure>
        </listitem>
        <listitem>This will create a new project called <emphasis>VirtuosoDataService</emphasis>.
          <figure id="ados3" float="1">
            <title>Create project</title>
            <graphic fileref="ui/eora3.png"/>
          </figure>
        </listitem>
        <listitem>Right click on the <emphasis>VirtuosoDataService</emphasis> project name of the
Solution Explorer pane, then select the <emphasis>Add -> New Item</emphasis> menu options.
          <figure id="ados4" float="1">
            <title>New Item</title>
            <graphic fileref="ui/einf4.png"/>
          </figure>
        </listitem>
        <listitem>The <emphasis>Add</emphasis> New Item dialog will appear, choose the
<emphasis>ADO.NET Entity Data Model</emphasis> template, give it the name <emphasis>Virtuoso.edmx</emphasis>
and click <emphasis>Add</emphasis> to start the creation of the ADO.Net Entity Data Model.
          <figure id="ados5" float="1">
            <title>Entity Model</title>
            <graphic fileref="ui/eora5.png"/>
          </figure>
        </listitem>
        <listitem>In the <emphasis>Entity Data Model Wizard</emphasis> dialog
<emphasis>Choose Model Contents</emphasis> page select the <emphasis>Generate from Database</emphasis> model
type and click <emphasis>Next</emphasis>.
          <figure id="ados6" float="1">
            <title>Model Contents</title>
            <graphic fileref="ui/eora6.png"/>
          </figure>
        </listitem>
        <listitem>In the <emphasis>Entity Data Model Wizard</emphasis> dialog
<emphasis>Choose your Data Connection</emphasis> page select the <emphasis>New Connection</emphasis> button
          <figure id="ados7" float="1">
            <title>Data Connection</title>
            <graphic fileref="ui/ados7.png"/>
          </figure>
        </listitem>
        <listitem>In the <emphasis>Choose Data Source</emphasis> dialog, select the
OpenLink <emphasis>Virtuoso Data Source</emphasis> from the list displayed and click <emphasis>Continue</emphasis>.
          <figure id="ados8" float="1">
            <title>Data Source</title>
            <graphic fileref="ui/dora9.png"/>
          </figure>
        </listitem>
        <listitem>In the <emphasis>Add Connection</emphasis> dialog, specify the <emphasis>hostname, portno,
        username and password</emphasis> for the target Virtuoso Server and check the <b>Save Password</b> check box.
          <figure id="ados9" float="1">
            <title>Connection Properties</title>
            <graphic fileref="ui/dora10.png"/>
          </figure>
        </listitem>
        <listitem>Select the <emphasis>Select Database From List</emphasis> radio button and choose
<emphasis>Demo</emphasis> from the drop down list, assuming the Virtuoso Demo Database is installed.
          <figure id="ados10" float="1">
            <title>Advanced Properties</title>
            <graphic fileref="ui/ados10.png"/>
          </figure>
        </listitem>
        <listitem>Click the <emphasis>Test Connection</emphasis> button to verify the connection is
successful and then click OK to add the connection.
          <figure id="ados11" float="1">
            <title>Test Connection</title>
            <graphic fileref="ui/ados11.png"/>
          </figure>
        </listitem>
        <listitem>Set the <emphasis>entity connect string</emphasis> name to <emphasis>VirtuosoDemoEntities</emphasis>
        (note this name as it is required in step 17 below) and click <emphasis>Next</emphasis>.
          <figure id="ados12" float="1">
            <title>entity connect string</title>
            <graphic fileref="ui/ados12.png"/>
          </figure>
        </listitem>
        <listitem>In the <emphasis>Choose your Database Objects</emphasis> page select the <emphasis>Tables</emphasis>
        check box to select all tables in the Demo database for addition to the Entity Data Model, set the
        <emphasis>Model Namespace</emphasis> to <emphasis>VirtuosoDemoModel</emphasis> and click <emphasis>Finish</emphasis>.
          <figure id="ados13" float="1">
            <title>Database Objects</title>
            <graphic fileref="ui/ados13.png"/>
          </figure>
        </listitem>
        <listitem>The <emphasis>Virtuoso.edmx</emphasis> EDM will be created with the tables and relationships displayed
        in the Visual Studio IDE
          <figure id="ados14" float="1">
            <title>Virtuoso.edmx</title>
            <graphic fileref="ui/ados14.png"/>
         </figure>
        </listitem>
        <listitem>Right click on the <emphasis>VirtuosoDataService</emphasis> project name of the
<emphasis>Solution Explorer pane</emphasis>, then select the <emphasis>Add -> New Item</emphasis> menu options.
          <figure id="ados4" float="1">
            <title>New Item</title>
            <graphic fileref="ui/ados4.png"/>
          </figure>
        </listitem>
        <listitem>The <emphasis>Add New Item</emphasis> dialog will appear, choose the
        <emphasis>ADO.NET Data Service</emphasis> template, give it the name <emphasis>Virtuoso.svc</emphasis> and click
        <emphasis>Add</emphasis> to create the ADO.Net Data Service.
          <figure id="ados15" float="1">
            <title>ADO.NET Data Service</title>
            <graphic fileref="ui/ados15.png"/>
          </figure>
        </listitem>
        <listitem>In the <emphasis>Virtuoso.svc.cs</emphasis> Data Service file created add the data source class
        name of <emphasis>VirtuosoDemoEntities</emphasis> (note this is the name set in step 12) as the
        <emphasis>DataService</emphasis> name and enable the access to the Data Service by adding the entry
        <emphasis>config.SetEntitySetAccessRule("*", EntitySetRights.All);</emphasis> in the
<emphasis>InitializeService</emphasis> method.
<programlisting><![CDATA[
// C#

using System;
using System.Web;
using System.Collections.Generic;
using System.ServiceModel.Web;
using System.Linq;
using System.Data.Services;

namespace SimpleDataService
{
    public class Northwind : DataService<VirtuosoDemoEntities>
    {
        public static void InitializeService(IDataServiceConfiguration  config)
        {
            config.SetEntitySetAccessRule("*", EntitySetRights.All);
        }
    }
}
]]></programlisting>
          <figure id="ados16" float="1">
            <title>Data Service</title>
            <graphic fileref="ui/ados16.png"/>
          </figure>
        </listitem>
        <listitem>To test the Data Service, simply hit <emphasis>Ctrl+F5</emphasis> within Visual Studio, which will
        start the development web server, run the Data Services server inside and load a Web browser page displaying
        the list of available tables/entities of the Demo database.
          <figure id="ados17" float="1">
            <title>test the Data Service</title>
            <graphic fileref="ui/ados17.png"/>
          </figure>
        </listitem>
        <listitem>To access a specific entity instance like the <emphasis>Customers</emphasis> table
<emphasis>ALFKI</emphasis> record, this would be specified as http://host/vdir/Virtuoso.svc/Customers('ALFKI') .
            <figure id="ados18" float="1">
              <title>Access a specific entity instance</title>
              <graphic fileref="ui/ados18.png"/>
            </figure>
         </listitem>
        </orderedlist>
        <para><emphasis>NOTES</emphasis></para>
        <orderedlist>
          <listitem><emphasis>Important</emphasis> - To view <emphasis>Atom</emphasis> (the default format returned by
          an ADO.NET Data Service) in Internet Explorer, you must first ensure that <emphasis>Feed Reading View</emphasis>
          is turned <emphasis>off</emphasis>. This can be done on the <emphasis>Content tab</emphasis> of <emphasis> Tools
          	in Internet Options</emphasis>.
          </listitem>
          <listitem>If a Data Services entity instance URI page fails to load you can turn
          	<emphasis>Verbose</emphasis> errors on by adding <emphasis>config.UseVerboseErrors = true;</emphasis> in the
          	<emphasis>virtuoso.svc.cs InitializeService</emphasis> method to obtain more detailed information from the
          	server as to why the page failed to load:
<programlisting><![CDATA[
public static void InitializeService(IDataServiceConfiguration config)

{

config.UseVerboseErrors = true;

config.SetEntitySetAccessRule("*", EntitySetRights.All);

}
]]></programlisting>
          </listitem>
        </orderedlist>
      </sect2>
  </sect1>

<sect1 id="installwfas">
	  <title>Windows Form Application for accessing Virtuoso RDF data via SPASQL using the Virtuoso ADO.Net Provider</title>
    <para>This section will guide you through creating a simple application that allows you to access RDF
data in a Virtuoso database as an Entity DataSet and explore that RDF data in an intuitive way by clicking
on dereferenceable <link linkend="rdfiriidtype">IRIs</link>.</para>
    <sect2 id="installwfasintro">
      <title>Pre-requisites</title>
<orderedlist>
  <listitem>Microsoft Visual Studio 2008</listitem>
  <listitem>The Virtuoso ADO.Net provider for .Net 3.5 and the Entity Framework.</listitem>
  <listitem>The example assumes that you have a local Virtuoso server with the Northwind demo database
installed. If the demo database is not already installed then download the <ulink url="http://download.openlinksw.com/packages/5.0/virtuoso/demo_dav.vad">demo database VAD package</ulink>
(demo_dav.vad) and install it. The VAD package will create a new database in Virtuoso called demo
containing the familiar Northwind tables. It will also creates <link linkend="rdfviewsrdbms">Linked Data Views</link> of the Northwind tables.
In the example we assume the database is accessible on a hostname of "demo.openlinksw.com" on the
default port 80, where an actually live instance of the Virtuoso Demo database is hosted. Users would
use the appropriate hostname and port number of their Virtuoso installation to create the sample
application, and would be would be example.com for a default installation or whatever the <link linkend="ini_URIQA">URIQA DefaultHost</link>
Virtuoso configuration parameter is set to when the demo database VAD package is installed.
  </listitem>
</orderedlist>
    </sect2>
    <sect2 id="installwfasgetstart">
      <title>Creating the Application</title>
      <para><emphasis>Step 1 - Create a view of the RDF data.</emphasis></para>
      <para>We want to be able to access the RDF data in Visual Studio and the easiest way to do this is to
create a view of the data that we are interested in and bind that view to a DataSet. This can be considered
as using server side <link linkend="rdfsparql">SPARQL</link>. Virtuoso supports an
<link linkend="rdfsparqlinline">extension to standard SQL that allows</link> execution of SPARQL.
If a SQL query begins with the keyword SPARQL then the rest of the query is interpreted by as SPARQL.
If a SPARQL query is used as the definition of a view then that view can be manipulated using SQL like
any other view. In this way the result set from a SPARQL query can be easily accessed from Visual Studio
using ADO.Net and the Entity Framework.
      </para>
      <para>
To create a view of the customers in the Northwind first open the Virtuoso Conductor and log in as dba.
Then open iSQL from the menu on the left and execute the following statement.
      </para>
<programlisting><![CDATA[

CREATE VIEW Demo.demo.sparqlview as
SPARQL
PREFIX nwind: <http://demo.openlinksw.com/schemas/northwind#>
SELECT DISTINCT  ?s
FROM <http://demo.openlinksw.com/Northwind>
WHERE {?s a nwind:Customer}
]]></programlisting>
<para>
<emphasis>Note:</emphasis> If the view is added to the Visual Studio project as user "demo" (or any other
than "dba'), then it must be ensured that the "SPARQL_SELECT" and "SPARQL_SPONGE" roles are assigned to
this user, which can be done via the Virtuoso Conductor in the "System Admin" -> "User Accounts" tab.
</para>
    <figure id="sparqlwinf1" float="1">
      <title>SPARQL_SPONGE</title>
      <graphic fileref="ui/sparqlwinf1.png"/>
    </figure>
      <para><emphasis>Step 2 - Create a simple grid form in Visual Studio</emphasis></para>
<orderedlist>
  <listitem>Open <emphasis>Visual Studio</emphasis> and create a new <emphasis>Windows Forms Application</emphasis> called RDFDemo.</listitem>
  <listitem>In the <emphasis>Form Designer</emphasis> drag a <emphasis>DataGridView</emphasis> on to the form.</listitem>
  <listitem>Click the <emphasis>Choose Data Source</emphasis> drop down and select <emphasis>Add Project Data Source</emphasis>.
    <figure id="sparqlwinf2" float="1">
      <title>Data Source</title>
      <graphic fileref="ui/sparqlwinf2.png"/>
    </figure>
  </listitem>
  <listitem>In the <emphasis>Data Source Configuration Wizard</emphasis> choose Database and then set up a connection to the demo database on your local Virtuoso server. </listitem>
  <listitem>On the <emphasis>Choose Your Data Objects</emphasis> page expand the <emphasis>Views</emphasis> and select sparqlview.
    <figure id="sparqlwinf3" float="1">
      <title>Data Source Configuration Wizard</title>
      <graphic fileref="ui/sparqlwinf3.png"/>
    </figure>
  </listitem>
  <listitem>Click <emphasis>Finish</emphasis>.</listitem>
  <listitem>In the <emphasis>Form Designer</emphasis> select dataGridView1 and change the <emphasis>AutoSizeColumnsMode</emphasis> to AllCellsExceptHeader.</listitem>
  <listitem>Select the <emphasis>DefaultCellStyle</emphasis> and click on the ellipsis. This will open the
<emphasis>CellStyleBuilder</emphasis>. Change the <emphasis>ForeColor</emphasis> to Blue.
    <figure id="sparqlwinf4" float="1">
      <title>CellStyleBuilder</title>
      <graphic fileref="ui/sparqlwinf4.png"/>
    </figure>
  </listitem>
  <listitem>Expand <emphasis>Font</emphasis> and change <emphasis>Underline</emphasis> to True.
Click <emphasis>OK</emphasis>.</listitem>
</orderedlist>
      <para><emphasis>Step 3 - Change the mapping of the DataSet.</emphasis></para>
<para>In the Solution Explorer you will now have a DataSet called DemoDataSet.xsd. If you double click on
this it opens the DataSet Designer. Select the column called s in the sparqlview table and in the Properties
pane change the DataType from System.String to System.Object.</para>
<para>The data returned by a SPARQL query can either be an <link linkend="rdfiriidtype">IRI</link> or a
literal value. In order to distinguish between the two the Virtuoso ADO.Net provider defines an additional
data type, SQLExtendedString. By setting the column type to System.Object we can cast the fetched data back
to SQLExtendedString and find out if an individual value is an IRI or a literal and handle it appropriately.
</para>
<para><emphasis>Step 4 - Create the on_click event handler for the cells in the DataGridView.</emphasis></para>
<para>Return to the <emphasis>Form Designer</emphasis> and double click on the cell of the
<emphasis>DataGridView</emphasis>. This creates the <emphasis>dataGridView1_CellContentClick</emphasis> method in Form1.cs. This is the method that handles clicking on IRI objects in the grid.
</para>
<para>Paste in the following block of code into the body of the <emphasis>dataGridView1_CellContentClick</emphasis> method.
</para>
<programlisting><![CDATA[
int column = e.ColumnIndex;
 object o = dataGridView1.Rows[e.RowIndex].Cells[e.ColumnIndex].Value;
 Type t = dataGridView1.Rows[e.RowIndex].Cells[e.ColumnIndex].ValueType;

 if (o is SqlExtendedString)
 {
     SqlExtendedString se = (SqlExtendedString) o;
     ExtendedStringHandler seHandler = new ExtendedStringHandler(se, this.sparqlviewTableAdapter.Connection);
     seHandler.displayData();
 }
 else if (o is SqlRdfBox)
 {
     //doesn't do anything at the moment
 }

]]></programlisting>
<para>
As we are using the SQLExtendedString extension from the Virtuoso ADO.Net provider you will also need to add
</para>
<programlisting><![CDATA[
using OpenLink.Data.Virtuoso;
]]></programlisting>
<para>
at the top of the file.
</para>
<para><emphasis>Step 5 - Create a class to handle exploring the RDF data.</emphasis></para>
<itemizedlist mark="bullet">
  <listitem>Add a new C# class to the project called ExtendedStringHandler, by Right clicking on
RDFDemo in the <emphasis>Solution Explorer</emphasis> and <emphasis>Add</emphasis> a
<emphasis>Class</emphasis>.</listitem>
  <listitem>Add the following using statements to the top of the file
<programlisting><![CDATA[
using OpenLink.Data.Virtuoso;
using System.Data;
using System.Windows.Forms;
using System.Drawing;
using System.Data.Mapping;
using System.Data.Common;
]]></programlisting>
</listitem>
  <listitem>Paste the following block of code into the class definition.
<programlisting><![CDATA[
StringBuilder DescribeCommand;
VirtuosoConnection ParentConnection;
List<Label> labelList = new List<Label>();
List<TextBox> textBoxList = new List<TextBox>();
DescribeDataSet describeDataSet = new DescribeDataSet();
Boolean isIRI = false;

public ExtendedStringHandler(SqlExtendedString iri, VirtuosoConnection parentConnection)
 {
     ParentConnection = parentConnection;
     if (iri.IriType == SqlExtendedStringType.IRI)
     {
         isIRI = true;
         DescribeCommand = new StringBuilder("sparql select * from <http://demo.openlinksw.com/Northwind> where {<" + iri.ToString() + "> ?p ?o}");      // Replace demo.openlinksw.com with your  URIQA DefaultHost setting
     }
 }

 public string describeCommandText
 {
     get
     {
         return DescribeCommand.ToString();
     }
 }

 public void getDescribeData()
 {
      VirtuosoCommand myCommand = new VirtuosoCommand(this.describeCommandText, this.ParentConnection);
     VirtuosoDataAdapter myAdapter = new VirtuosoDataAdapter();
     myAdapter.SelectCommand = myCommand;
     myAdapter.Fill(describeDataSet.DataTable1);
 }

 public void displayData()
 {
     if (isIRI)
     {
         getDescribeData();
         Form describeForm = new Form();
         describeForm.AutoScroll = true;
         describeForm.Width = 840;

         Label label1 = new Label();
         label1.AutoSize = true;
         label1.Font = new Font(label1.Font.FontFamily, label1.Font.Size + 3.0F, label1.Font.Style | FontStyle.Bold, label1.Font.Unit);
         describeForm.Controls.Add(label1);

         DataTable table1 = describeDataSet.Tables[0];
         if (table1.Rows.Count == 0)
             label1.Text = "No Details Available";
         else
         {
             foreach (DataRow row in table1.Rows)
                 if (row[0].ToString() == "http://www.w3.org/1999/02/22-rdf-syntax-ns#type")
                 {
                     StringBuilder title = new StringBuilder(row[1].ToString() + " details");
                     label1.Text = title.ToString();
                     break;
                 }

             foreach (DataRow row in table1.Rows)
             {
                 Label propertyLabel = new Label();
                 TextBox valueBox = new TextBox();
                 valueBox.Width = 400;

                 object property = row[0];
                 object value = row[1];

                 if (value is SqlExtendedString)
                 {
                     valueBox.ForeColor = Color.Blue;
                     valueBox.Font = new Font(valueBox.Font.FontFamily, valueBox.Font.Size, valueBox.Font.Style | FontStyle.Underline, valueBox.Font.Unit);
                 }
                 propertyLabel.Text = row[0].ToString();
                 propertyLabel.AutoEllipsis = true;
                 propertyLabel.AutoSize = false;
                 propertyLabel.Width = propertyLabel.PreferredWidth > 380 ? 380 : propertyLabel.PreferredWidth;

                 Binding bind = new Binding("Text", row[1], "");
                 valueBox.DataBindings.Add(bind);

                 labelList.Add(propertyLabel);
                 textBoxList.Add(valueBox);
             }

             for (int i = 0; i < table1.Rows.Count; i++)
             {
                 textBoxList[i].Click += new EventHandler(this.iri_Click);
                 labelList[i].Location = new Point(10, i * 20 + 50);
                 textBoxList[i].Location = new Point(400, i * 20 + 50);
                 describeForm.Controls.Add(labelList[i]);
                 describeForm.Controls.Add(textBoxList[i]);
             }

             describeForm.Height = labelList.Count * 20 + 100 > 500 ? 500 : labelList.Count * 20 + 100;
         }
         describeForm.ShowDialog();
     }
     else
     {
         Form blankForm = new Form();
         Label label1 = new Label();
         label1.Text = "Blank Node";
         label1.Font = new Font(label1.Font.FontFamily, label1.Font.Size + 3.0F, label1.Font.Style | FontStyle.Bold, label1.Font.Unit);
         blankForm.ShowDialog();
     }
 }

 public void iri_Click(object sender, EventArgs e)
 {
     int boxNum = 0;

     for (int i = 0; i < textBoxList.Count; i++)
     {
         if (sender == textBoxList[i])
         {
             boxNum = i;
             break;
         }
     }

    Object o = describeDataSet.DataTable1.Rows[boxNum][1];
     if (o is SqlExtendedString)
     {
         SqlExtendedString se = (SqlExtendedString)o;
         ExtendedStringHandler seHandler = new ExtendedStringHandler(se, ParentConnection);
         seHandler.displayData();
     }
     else if (o is SqlRdfBox)
     {
        //doesn't do anything at the moment
    }
 }
]]></programlisting>
</listitem>
</itemizedlist>
<para>
The ExtendedStringHandler class creates a new SPARQL query based on the IRI that was clicked. This
query is executed against Virtuoso using the ADO.Net connection in the same way that any SQL statement
would be executed across an ADO.Net connection. This can be considered as Client Side SPARQL. The result
set from the query describes the selected object and is returned as an ADO.Net DataAdapter. The
DataAdapter is used to fill a DataTable which is displayed on a new form. We now need to add the
new DataSet to the project and define the DataTable that will hold the query results.
</para>
      <para><emphasis>Step 6 - Add a new DataSet to hold the query results.</emphasis></para>
<orderedlist>
  <listitem>Right click RDFDemo in the <emphasis>Solution Explorer</emphasis> and add a new
<emphasis>DataSet</emphasis>. Call the new <emphasis>DataSet</emphasis> DescribeDataSet.
    <figure id="sparqlwinf5" float="1">
      <title>Add a new DataSet</title>
      <graphic fileref="ui/sparqlwinf5.png"/>
    </figure>
</listitem>
  <listitem>Double click on DescribeDataSet in the <emphasis>Solution Explorer</emphasis> to open the
<emphasis>DataSet</emphasis> Designer and drag a <emphasis>DataTable</emphasis> from the
<emphasis>Toolbox</emphasis> into it.</listitem>
  <listitem>Add two columns, p and o, to the <emphasis>DataTable</emphasis> and set the
<emphasis>DataType</emphasis> of each column to System.Object.
    <figure id="sparqlwinf6" float="1">
      <title>Add two columns</title>
      <graphic fileref="ui/sparqlwinf6.png"/>
    </figure></listitem>
</orderedlist>
      <para><emphasis>Step 7 - Build and run the application.</emphasis></para>
<para>You should see a form displaying all the Northwind customers, like this.
</para>
    <figure id="sparqlwinf7" float="1">
      <title>Northwind customers</title>
      <graphic fileref="ui/sparqlwinf7.png"/>
    </figure>
<para>When any customer is clicked it opens a new form showing customer details.
</para>
    <figure id="sparqlwinf8" float="1">
      <title>Customer details</title>
      <graphic fileref="ui/sparqlwinf8.png"/>
    </figure>
<para>Clicking on the links in the new form allows you to drill down further to get
order, product, location details etc.
</para>
    <figure id="sparqlwinf9" float="1">
      <title>Order, product, location details</title>
      <graphic fileref="ui/sparqlwinf9.png"/>
    </figure>
<para>and</para>
    <figure id="sparqlwinf10" float="1">
      <title>Order, product, location details</title>
      <graphic fileref="ui/sparqlwinf10.png"/>
    </figure>
      <para><emphasis>Next Steps</emphasis></para>
<para>
You will notice if you keep clicking on the links that this application will only display data that
is held in the Northwind graph. Clicking on an external link, for example the link to Berlin in
dbpedia, http://dbpedia.org/resource/Berlin, results in a empty window and an error message. The
next step is to extend this application so that it can handle dereferencing external IRIs.
</para>
    </sect2>
    <sect2 id="installwfasxtendcomlab">
      <title>Extending RDFDemo to Allow Dereferencing of External IRIs</title>
<para>
This section will guide you through extending the application created in
<link linkend="installwfasgetstart">Creating a Windows Forms Application To Access RDF Data Using The
Virtuoso ADO.Net Provider</link> so that it will dereference external IRIs.
</para>
      <para><emphasis>Pre-requisites</emphasis></para>
<orderedlist>
  <listitem>A working copy of the RDFDemo application created in
<link linkend="installwfasgetstart">Creating a Windows Forms Application To
Access RDF Data Using The Virtuoso ADO.Net Provider.</link></listitem>
</orderedlist>
    <sect3 id="installwfasxtendcomlabextappl">
      <title>Extending the Application</title>
<para>In RDFDemo when the sparql endpoint is queried to get the description of the selected item it executes
a query that is restricted to the local Northwind dataset. The query is something like
</para>
<programlisting><![CDATA[
SPARQL
PREFIX nwind: <http://demo.openlinksw.com/schemas/northwind#>
SELECT DISTINCT  ?s
FROM <http://demo.openlinksw.com/Northwind>
WHERE {?s a nwind:Customer}
]]></programlisting>
<para>If you examine the ExtendedStringHandler class you will see that the dataset clause, from
&lt;http://example.com/Northwind&gt;, is hard coded. This means that when when the selected IRI is
a link to an external data store, such as dbpedia, there is no matching data and an error is displayed.
If the application is to be able to dereference external IRIs then the hard coded dataset clause needs
to be removed and then we can use a Virtuoso extension to SPARQL, get:soft, that tells Virtuoso that it
needs to go and look elsewhere for the graph. However, this will result in a loss of performance when
exploring the local Northwind dataset. To minimize the impact on performance we will first query the
local Northwind dataset and if there are no matching triples returned then we will use a more generic
query that will look elsewhere for matching data.
</para>
      <para><emphasis>Step 1 - Add the alternative query to the ExtendedString Class.</emphasis></para>
<itemizedlist mark="bullet">
  <listitem>Open the RDFDemo project in Visual Studio </listitem>
  <listitem>Open the ExtendedStringHandler class.</listitem>
  <listitem>Remove DescribeCommand by removing the line
<programlisting><![CDATA[
StringBuilder DescribeCommand;
]]></programlisting>
<para>
and substitute the following:
</para>
<programlisting><![CDATA[
StringBuilder DescribeCommandSimple, DescribeCommandGeneral;
]]></programlisting>
</listitem>
  <listitem>In the ExtendedStringHandler constructor the sparql query that was DescribeCommand becomes
DescribeCommandSimple and we define a new query for DescribeCommandGeneral.
<programlisting><![CDATA[
DescribeCommandSimple = new StringBuilder("sparql select * from <http://demo.openlinksw.com/Northwind> where {<" + iri.ToString() + "> ?p ?o}");       // Replace demo.openlinksw.com with your  URIQA DefaultHost setting
DescribeCommandGeneral = new StringBuilder("sparql define get:soft " + '"'.ToString() + "soft" + '"'.ToString() + " select * from <" + iri.ToString() + "> where { <" + iri.ToString() + "> ?p ?o }");
]]></programlisting>
</listitem>
  <listitem>The single describeCommand property needs to be replaced with the two new properties,
DescribeCommandSimple and DescribeCommandGeneral
<programlisting><![CDATA[
public string describeCommandSimpleText
{
    get
    {
        return DescribeCommandSimple.ToString();
    }
}
public string describeCommandGeneralText
{
    get
    {
        return DescribeCommandGeneral.ToString();
    }
}
]]></programlisting>
</listitem>
  <listitem>Finally, the getDescribeData method needs changing to:
<programlisting><![CDATA[
public void getDescribeData()
{
    VirtuosoCommand myCommand = new VirtuosoCommand(this.describeCommandSimpleText, this.ParentConnection);
    VirtuosoDataAdapter myAdapter = new VirtuosoDataAdapter();
    myAdapter.SelectCommand = myCommand;
    myAdapter.Fill(describeDataSet.DataTable1);
    // Tried the simple version if fails to get the data try
    // to look elsewhere.
    if (describeDataSet.DataTable1.Rows.Count == 0)
    {
        myCommand.CommandText = describeCommandGeneralText;
        myAdapter.Fill(describeDataSet.DataTable1);
    }
}
]]></programlisting>
</listitem>
</itemizedlist>
      <para><emphasis>Step 2 - Build and Run the Application</emphasis></para>
<para>
You will see the same starting form:
</para>
    <figure id="sparqlwinf11" float="1">
      <title>Build and Run the Application</title>
      <graphic fileref="ui/sparqlwinf11.png"/>
    </figure>
<para>
Select a Customer and then select the link to the City in dbpedia. This will now open up another window
displaying information about the city from dbpedia. Be patient as it may take a little while to open.
</para>
    <figure id="sparqlwinf12" float="1">
      <title>Customer</title>
      <graphic fileref="ui/sparqlwinf12.png"/>
    </figure>
      <para><emphasis>Step 3 - Changing the Form Title</emphasis></para>
<para>
Notice that in displayData method that we look for a
http://www.w3.org/1999/02/22-rdf-syntax-ns#type and create a title for the form from it.
</para>
<programlisting><![CDATA[
foreach (DataRow row in table1.Rows)
  if (row[0].ToString() == "http://www.w3.org/1999/02/22-rdf-syntax-ns#type")
  {
      StringBuilder title = new StringBuilder(row[1].ToString() + " details");
      label1.Text = title.ToString();
      break;
  }
]]></programlisting>
<para>
This worked well for the Northwind subjects but less well now we are getting data from other graphs.
To change the title of the forms used to display the data:
</para>
<itemizedlist mark="bullet">
  <listitem>Add an new member variable to hold the IRI that we exploring to the bock of member variables
<programlisting><![CDATA[
StringBuilder DescribeCommandSimple, DescribeCommandGeneral;
VirtuosoConnection ParentConnection;
List<Label> labelList = new List<Label>();
List<TextBox> textBoxList = new List<TextBox>();
DescribeDataSet describeDataSet = new DescribeDataSet();
Boolean isIRI = false;
SqlExtendedString ParentIRI;
]]></programlisting>
</listitem>
  <listitem>Assign a value to ParentIRI in the constructor:
<programlisting><![CDATA[
public ExtendedStringHandler(SqlExtendedString iri, VirtuosoConnection parentConnection)
  {
      ParentConnection = parentConnection;
      if (iri.IriType == SqlExtendedStringType.IRI)
      {
          ParentIRI = iri;
          isIRI = true;
          DescribeCommandSimple = new StringBuilder("sparql select * from <http://demo.openlinksw.com/Northwind> where {<" + iri.ToString() + "> ?p ?o}");      // Replace demo.openlinksw.com with your  URIQA DefaultHost setting
          DescribeCommandGeneral = new StringBuilder("sparql define get:soft " + '"'.ToString() + "soft" + '"'.ToString() + " select * from <" + iri.ToString() + "> where { <" + iri.ToString() + "> ?p ?o }");
      }
  }
]]></programlisting>
</listitem>
  <listitem>Remove the existing foreach block that sets the form title and replace with the following lines:
<programlisting><![CDATA[
StringBuilder title = new StringBuilder(ParentIRI.ToString() + " details");
label1.Text = title.ToString();
]]></programlisting>
</listitem>
  <listitem>Build and run the application.
    <figure id="sparqlwinf13" float="1">
      <title>Build and run the application</title>
      <graphic fileref="ui/sparqlwinf13.png"/>
    </figure>
</listitem>
</itemizedlist>
<para><emphasis>Next Steps</emphasis></para>
<para>The application now allows you to explore data and follow links from your locally held data into the
external web of data. Looking at the data displayed in the form it would be nice to make the labels for
the properties more compact. The label http://dbpedia.org/property/population is a very precise definition
but for our purposes it would be clearer to label the property just population. In the next step will be
to modify the application so that it displays more readable labels.
</para>
    </sect3>
    </sect2>
    <sect2 id="installwfasxtendcomplab">
      <title>Extending RDFDemo to Display More Compact Labels</title>
<para>
This section will guide you through extending the application created in
<link linkend="installwfasxtendcomlab">Extending RDFDemo to Allow Dereferencing of External IRIs</link> so that the data is displayed in a more readable form.
</para>
      <para><emphasis>Pre-requisites</emphasis></para>
<orderedlist>
  <listitem>A working copy of the RDFDemo application created in
<link linkend="installwfasxtendcomlab">Extending RDFDemo to Allow Dereferencing of External IRIs</link></listitem>
</orderedlist>
    <sect3 id="installwfasxtendcomplabextapp">
      <title>Extending the Application</title>
<para>The RDF demo application presents the user with a list of Customers from the Northwind database in
the form of dereferenceable IRIs. When a customer is selected from the list the application uses a sparql
query to describe that customer and the results are displayed in a form as rows of labels and data. The
labels correspond to RDF predicates and the data corresponds to RDF objects while the subject is the
customer initially selected. In many cases the objects are dereferencable IRIs which are then used as
the subject when the 'drilling down' into the data. However, the predicates are also IRIs so it is
possible to gain more information about these as well.
</para>
<para>The RDF Schema defines a property http://www.w3.org/2000/01/rdf-schema#label that may be used to
provide a human-readable version of a resource's name. We can obtain further details of each of the
predicates in a resultset and check to see if one of the properties is an
http://www.w3.org/2000/01/rdf-schema#label. If it is we can use the associated text as the label in
our form instead of the the predicate IRI. The benefit should be a more human readable form.
</para>
      <para><emphasis>Step 1 - Add a New Method to Get the Label Text</emphasis></para>
<para>This method takes the predicate IRI and issues a sparql query to get its description. It then
cycles through the returned dataset to find a http://www.w3.org/2000/01/rdf-schema#label. If there is
one then the associated text is returned by the method. Otherwise the method returns the IRI string.
</para>
<itemizedlist mark="bullet">
  <listitem>Add the following method to the ExtendedStringHandlerClass
<programlisting><![CDATA[
private string getLabelText(Object label)
  {
      string labelText = label.ToString();
      if (label is SqlExtendedString)
      {
          SqlExtendedString se = (SqlExtendedString)label;
          StringBuilder getLabelCommandText = new StringBuilder("sparql define get:soft \"soft\" select * from <" + se.ToString() + "> where {<" + se.ToString() + "> ?p ?o}");
          VirtuosoCommand getLabelCommand = new VirtuosoCommand(getLabelCommandText.ToString(), ParentConnection);
          VirtuosoDataAdapter getLabelAdapter = new VirtuosoDataAdapter();
          getLabelAdapter.SelectCommand = getLabelCommand;
          DataSet getLabelDataSet = new DataSet();
          try
          {
              getLabelAdapter.Fill(getLabelDataSet);
              foreach (DataRow getLabelRow in getLabelDataSet.Tables[0].Rows)
              {
                  if (getLabelRow[0].ToString() == "http://www.w3.org/2000/01/rdf-schema#label")
                  {
                      labelText = getLabelRow[1].ToString();
                      break;
                  }
              }
          }
          catch
          {
          }
      }
      return labelText;
  }
]]></programlisting>
</listitem>
  <listitem>Change the line in displayData from
<programlisting><![CDATA[
propertyLabel.Text = row[0].ToString();
]]></programlisting>
</listitem>
  <listitem>to
<programlisting><![CDATA[
propertyLabel.Text = getLabelText(row[0]);
]]></programlisting>
</listitem>
</itemizedlist>
       <para><emphasis>Step 1 - Add a New Method to Get the Label Text</emphasis></para>
<para>When you run the application you will see that the initial form is the same. In fact, when you
select the Customer you will also see that the customer details are also the same. It is only when you
start exploring data outside the Northwind graph that you will see the labels in the form change.
</para>
    <figure id="sparqlwinf14" float="1">
      <title>Northwind graph</title>
      <graphic fileref="ui/sparqlwinf14.png"/>
    </figure>
    <para><emphasis>Next Steps</emphasis></para>
<para>It is clear from running the application that the Northwind ontology does not define an
http://www.w3.org/2000/01/rdf-schema#label for its members. In order to benefit from this modified
version of RDFDemo we need to update our Northwind ontology so that
http://www.w3.org/2000/01/rdf-schema#label is defined for each resource. The next step will be to modify
our Northwind ontology.
</para>
     </sect3>
    </sect2>
    <sect2 id="installwfasmodify">
      <title>Modifying the Northwind Ontology to Add Labels</title>
<para>This section will guide you through modifying the Northwind Ontology created when you installed
the <ulink url="http://download.openlinksw.com/packages/5.0/virtuoso/demo_dav.vad">demo database VAD package</ulink> so that each resources is identified by an
http://www.w3.org/2000/01/rdf-schema#label. This will improve the readability of the information displayed by
the application created in <link linkend="installwfasxtendcomplab">Extending RDFDemo to Display More Compact Labels</link>.
</para>
<para><emphasis>Pre-requisites</emphasis></para>
<orderedlist>
  <listitem>A working copy of the RDFDemo application created in <link linkend="installwfasxtendcomplab">Extending RDFDemo to Display More Compact Labels</link></listitem>
</orderedlist>
    <sect3 id="installwfasmodifyeditont">
      <title>Editing the Ontology</title>
    <para><emphasis>Get a Working Copy of the Northwind Ontology</emphasis></para>
<para>The the file describing the Northwind Ontology, nw.owl, is installed in the DAV when the demo vad
is loaded. To get a working copy open the Virtuoso Conductor and log in as dba. Select WebDAV Browser in
the navigation panel on the left. This will open a window that allows you to browse the WebDAV Repository.
The Northwind Ontology file can be found in DAV/VAD/demo/sql. Take a copy of the file.
</para>
    <para><emphasis>Editing nw.owl</emphasis></para>
<para>In the first instance is edited nw.owl so that the property name consistently begin with a lower
case letter. This matches the results for describing resources held in the Northwind database. Also are
added missing properties so that there should be a label in all cases.
</para>
    <para><emphasis>Registering the Changes in Virtuoso</emphasis></para>
<para>There are two methods for registering the changes in Virtuoso:
</para>
<orderedlist>
  <listitem>Method I:
    <itemizedlist mark="bullet">
      <listitem>Copy the edited version of nw.owl back into the DAV.</listitem>
      <listitem>In isql, load the script load_ontology_dav.sql and execute it. The new version of
nw.owl will then be used</listitem>
    </itemizedlist>
</listitem>
  <listitem>
    <itemizedlist mark="bullet">
      <listitem>Ensure that your new version of nw.owl is in a folder accessible by Virtuoso. You may
need to edit your virtuoso.ini file and restart the server.</listitem>
      <listitem>In isql, load the script load_ontology_file.sql and edit it so that it has the full
path to the new version of nw.owl</listitem>
      <listitem>Run the script. The new version of nw.owl will then be used.</listitem>
    </itemizedlist>
</listitem>
</orderedlist>
    <para>Modify RDFDemo so that it looks for the graph used to describe the Northwind data and
searches that graph for the predicate details:</para>
<orderedlist>
  <listitem>Add a new member variable to the ExtendedStringHandler class to hold the graphs that
we need to search for the predicate information.
<programlisting><![CDATA[
StringBuilder DescribeCommandSimple, DescribeCommandGeneral;
VirtuosoConnection ParentConnection;
List<Label> labelList = new List<Label>();
List<TextBox> textBoxList = new List<TextBox>();
List<String> graphList = new List<String>();
DescribeDataSet describeDataSet = new DescribeDataSet();
Boolean isIRI = false;
SqlExtendedString ParentIRI;
]]></programlisting></listitem>
  <listitem>In displayData, after we have set the title of the form, add the following block of code:
<programlisting><![CDATA[
// Later we will want to get property labels and for that
 // we will need the graph where the resource is defined.
foreach (DataRow row in table1.Rows)
     if (row[0].ToString() == "http://www.openarchives.org/ore/terms/isDescribedBy"
    && row[1].ToString() != ParentIRI.ToString())
     {
         String graph = row[1].ToString();
         graphList.Add(graph);
     }
]]></programlisting>
</listitem>
  <listitem>Replace the existing getLabelText method with an extended version
<programlisting><![CDATA[
 private string getLabelText(Object label)
  {
      string labelText = label.ToString();
      if (label is SqlExtendedString)
      {
          Boolean foundLabel = false;
          SqlExtendedString se = (SqlExtendedString)label;
          VirtuosoDataAdapter getLabelAdapter = new VirtuosoDataAdapter();
          DataSet getLabelDataSet = new DataSet();

          //Try finding it in resources graph first
          foreach (String graph in graphList)
          {
              StringBuilder getLabelCommandText = new StringBuilder("sparql select * from <" + graph + "> where {<" + se.ToString() + "> ?p ?o}");
              VirtuosoCommand getLabelCommand = new VirtuosoCommand(getLabelCommandText.ToString(), ParentConnection);
              getLabelAdapter.SelectCommand = getLabelCommand;

              try
              {
                  getLabelAdapter.Fill(getLabelDataSet);
                  foreach (DataRow getLabelRow in getLabelDataSet.Tables[0].Rows)
                  {
                      if (getLabelRow[0].ToString() == "http://www.w3.org/2000/01/rdf-schema#label")
                      {
                          labelText = getLabelRow[1].ToString();
                          foundLabel = true;
                          break;
                      }
                  }
              }
              catch
              {
              }
              if (foundLabel)
                  break;
          }
          // If we still have no label try the predicate itself as the graph
          if (!foundLabel)
          {
              StringBuilder getLabelCommandText = new StringBuilder("sparql define get:soft \"soft\" select * from <" + se.ToString() + "> where {<" + se.ToString() + "> ?p ?o}");
              VirtuosoCommand getLabelCommand = new VirtuosoCommand(getLabelCommandText.ToString(), ParentConnection);
              getLabelAdapter.SelectCommand = getLabelCommand;
              try
              {
                  getLabelAdapter.Fill(getLabelDataSet);
                  foreach (DataRow getLabelRow in getLabelDataSet.Tables[0].Rows)
                  {
                      if (getLabelRow[0].ToString() == "http://www.w3.org/2000/01/rdf-schema#label")
                      {
                          labelText = getLabelRow[1].ToString();
                          break;
                      }
                  }
              }
              catch
              {
              }
          }
      }
      return labelText;
  }
]]></programlisting>
<para>This extended method first checks the graphs in the graph list for the predicate information then
if no label has been found tries the predicate itself as the graph.
</para>
</listitem>
  <listitem>Build and run, the Northwind resources should now be correctly and concisely labeled
    <figure id="sparqlwinf15" float="1">
      <title>Northwind resources</title>
      <graphic fileref="ui/sparqlwinf15.png"/>
    </figure>
</listitem>
</orderedlist>
<para>
</para>
    <para><emphasis>Improving The Appearance of the Form</emphasis></para>
<para>The following changes are not strictly necessary but improve the appearance of the form:
</para>
<itemizedlist mark="bullet">
  <listitem>Line up the right hand edge of the labels with the text boxes by setting TextAlign to
MiddleRight and reduce the width of the labels.
<programlisting><![CDATA[
propertyLabel.Text = getLabelText(row[0]);
propertyLabel.AutoEllipsis = true;
propertyLabel.AutoSize = false;
propertyLabel.Width = 130;
propertyLabel.TextAlign = ContentAlignment.MiddleRight;
]]></programlisting>
</listitem>
  <listitem>Make the form narrower:
<programlisting><![CDATA[
describeForm.Width = 660;
]]></programlisting>
</listitem>
  <listitem>Alter the positioning of the labels and TextBoxes on the form:
<programlisting><![CDATA[
textBoxList[i].Click += new EventHandler(this.iri_Click);
labelList[i].Location = new Point(10, i * 22 + 50);
textBoxList[i].Location = new Point(150, i * 22 + 50);
describeForm.Controls.Add(labelList[i]);
describeForm.Controls.Add(textBoxList[i]);
]]></programlisting>
    <figure id="sparqlwinf16" float="1">
      <title>Alter the positioning</title>
      <graphic fileref="ui/sparqlwinf16.png"/>
    </figure>
</listitem>
</itemizedlist>
    <para><emphasis>Next Steps</emphasis></para>
<para>The image below shows some of the information about an employee in the Northwind dataset.
</para>
    <figure id="sparqlwinf17" float="1">
      <title>employee</title>
      <graphic fileref="ui/sparqlwinf17.png"/>
    </figure>
<para>In the next step we will extend the application so the images and web pages can be viewed
and long text fields are displayed in full.
</para>
    </sect3>
    </sect2>

    <sect2 id="installwfasxtendlongtext">
      <title>Extending RDFDemo to Display Images and Longer Text Fields.</title>
<para>This section will guide you through extending RDFDemo so that longer text fields can be displayed
as a block of text and so that links to images and web pages can be viewed in a browser window.
</para>
<para><emphasis>Pre-requisites</emphasis></para>
<orderedlist>
  <listitem>A working copy of the RDFDemo application created in
<link linkend="installwfasmodify">Modifying the Northwind Ontology to Add Labels</link></listitem>
</orderedlist>
    <sect3 id="installwfasxtendlongtextmodf">
      <title>Modifying the Application</title>
    <para><emphasis>Displaying Text</emphasis></para>
<para>We will modify the form that show the details of the selected item so that when the text in the boxes
is too long to be seen in full a button will appear beside the box on the form and if you click the button
the complete text will be displayed in a separate window.
</para>
<orderedlist>
  <listitem>Add a new class, MoreButton that extends System.Windows.Forms.Button.
<itemizedlist mark="bullet">
  <listitem>In the <emphasis>Solution Explorer</emphasis> right click on the RDFDemo project and select
<emphasis>Add</emphasis> then <emphasis>New Item</emphasis>.</listitem>
  <listitem>Add a new class called MoreButton.cs.
    <figure id="sparqlwinf18" float="1">
      <title>Add a new class</title>
      <graphic fileref="ui/sparqlwinf18.png"/>
    </figure>
</listitem>
  <listitem>The following using statement goes at the top of the file:
<programlisting><![CDATA[
using System.Windows.Forms;
]]></programlisting>
</listitem>
  <listitem>The MoreButton class must inherit from System.Windows.Forms.Button
so the class definition line should look like this:
<programlisting><![CDATA[
class MoreButton : Button
]]></programlisting>
</listitem>
  <listitem>Add the following code to the body of the MoreButton class:
<programlisting><![CDATA[
 String longText;

 public MoreButton(String text)
 {
     longText = text;
     this.Text = "More";
 }

 protected override void  OnClick(EventArgs e)
 {
     Form moreForm = new Form();
     TextBox moreBox = new TextBox();
     moreBox.Text = longText;
     moreBox.Width = 300;
     moreBox.Height = 250;
     moreBox.ScrollBars = ScrollBars.Vertical;
     moreBox.Multiline = true;
     moreBox.WordWrap = true;
     moreBox.Select(0, 0);
     moreBox.ReadOnly = true;
     moreForm.Controls.Add(moreBox);
     moreForm.Width = 320;
     moreForm.Height = 280;
     moreForm.ShowDialog();
 }
]]></programlisting>
</listitem>
</itemizedlist>
</listitem>
  <listitem>In displayData in the ExtendedStringHandler class, when the labels and TextBoxes are added to
the form check if the text is too big for the box. If it is then add a MoreButton that will display all
the text in a separate window.
<programlisting><![CDATA[
if (textBoxList[i].DataBindings[0].DataSource.ToString().Length > 80
    && !(textBoxList[i].DataBindings[0].DataSource is SqlExtendedString))
{
    moreButtonList.Add(new MoreButton(textBoxList[i].DataBindings[0].DataSource.ToString()));
    moreButtonList[moreButtonList.Count - 1].Location = new Point(550, i * 22 + 50);
    describeForm.Controls.Add(moreButtonList[moreButtonList.Count -1]);
}
]]></programlisting>
</listitem>
  <listitem>We will also need a list to hold the buttons as they are created so the following needs to
be added to the member variables at the top of the ExtendedStringHandler class.
<programlisting><![CDATA[
List<MoreButton> moreButtonList = new List<MoreButton>();
]]></programlisting>
</listitem>
  <listitem>Build and run the application. If you click through to an Employee page you will see the
Notes field now has a button labeled More next to it. If you click on that button the text from the Notes
field is displayed in a new window.
    <figure id="sparqlwinf19" float="1">
      <title>Notes</title>
      <graphic fileref="ui/sparqlwinf19.png"/>
    </figure>
</listitem>
</orderedlist>
    <para><emphasis>Displaying Images and Web Pages</emphasis></para>
<para>Next we will modify the form so that item identified as images or web pages will be opened in a
browser window. Again we will do this by adding a button beside the box on the form that will open the
browser window.
</para>
<orderedlist>
  <listitem>Add a new class, OpenButton that extends System.Windows.Forms.Button.
<itemizedlist mark="bullet">
  <listitem>In the <emphasis>Solution Explorer</emphasis> right click on the RDFDemo project and select
<emphasis>Add</emphasis> then <emphasis>New Item</emphasis>
</listitem>
   <listitem>Add a new class called OpenButton.cs.
</listitem>
   <listitem>The following using statement goes at the top of the file:
<programlisting><![CDATA[
using System.Windows.Forms;
]]></programlisting>
</listitem>
   <listitem>The OpenButton class must inherit from System.Windows.Forms.Button so the class
definition line should look like this:
<programlisting><![CDATA[
class OpenButton : Button
]]></programlisting>
</listitem>
   <listitem>Add the following code to the body of the OpenButton class:
<programlisting><![CDATA[
String urlText;

public OpenButton(String text)
{
    urlText = text;
    this.Text = "Open";
}

protected override void  OnClick(EventArgs e)
{
    System.Diagnostics.Process.Start(urlText);
}
]]></programlisting>
</listitem>
</itemizedlist>
</listitem>
  <listitem>In displayData in the ExtendedStringHandler class, where we added the code to check for long
text fields we now need to check for IRIs that identify images and web pages. As a simple first attempt
we will check for matching labels. So for example, if a property label is 'image' or 'webpage', we will
assume it can be opened in a browser window and put an OpenButton beside it.
<programlisting><![CDATA[
if (labelList[i].Text == "website"
    || labelList[i].Text == "image"
    || labelList[i].Text == "depiction"
    || labelList[i].Text == "page"
    || labelList[i].Text == "url"
    || labelList[i].Text == "image skyline")
{
    openButtonList.Add(new OpenButton(textBoxList[i].DataBindings[0].DataSource.ToString()));
    openButtonList[openButtonList.Count - 1].Location = new Point (550, i * 22 + 50);
    describeForm.Controls.Add(openButtonList[openButtonList.Count - 1]);
}
]]></programlisting>
</listitem>
  <listitem>We will also need a list to hold the buttons as they are created so the following needs to
be added to the member variables at the top of the ExtendedStringHandler class.
<programlisting><![CDATA[
List<OpenButton> openButtonList = new List<OpenButton>();
]]></programlisting>
</listitem>
  <listitem>Build and run the application. If you click through to an Employee page now you will see that
the Image field now has a button labeled Open next to it. If you click on that button the image is opened
in your default browser.
    <figure id="sparqlwinf20" float="1">
      <title>Image</title>
      <graphic fileref="ui/sparqlwinf20.png"/>
    </figure>
</listitem>
</orderedlist>
    <para><emphasis>Next Steps</emphasis></para>
<para>It has already been mentioned that the property labels are also dereferenceable IRIs. We used this
feature to find a short name to display rather that the complete IRI. The next step is to make the labels
clickable so the ontology itself can also be explored.
</para>
    </sect3>
    </sect2>


    <sect2 id="installwfasxtendproplab">
      <title>Extending RDFDemo To Make The Property Labels Clickable</title>
<para>This section will guide you through extending RDFDemo to make the property labels clickable. Clicking
on the property label will take you to a page describing that property.
</para>
<para><emphasis>Pre-requisites</emphasis></para>
<orderedlist>
  <listitem>A working copy of the RDFDemo application created in
<link linkend="installwfasxtendlongtext">Extending RDFDemo to Display Images and Longer Text Fields</link></listitem>
</orderedlist>
    <sect3 id="installwfasxtendproplabmod">
      <title>Modifying the Application</title>
    <para><emphasis>Making the Labels Clickable</emphasis></para>
<para>Making the property labels clickable is fairly straight forward. We will use basically the same code
as is used to make the values clickable.
</para>
<orderedlist>
  <listitem>First we need to add a new event handler. In the ExtendedStringHandler class modify displayData
to add an event handler for each of the property labels.
<programlisting><![CDATA[
for (int i = 0; i < table1.Rows.Count; i++)
{
    textBoxList[i].Click += new EventHandler(this.iri_Click);
    labelList[i].Location = new Point(10, i * 22 + 50);
    textBoxList[i].Location = new Point(150, i * 22 + 50);
    describeForm.Controls.Add(labelList[i]);
    describeForm.Controls.Add(textBoxList[i]);
]]></programlisting>
<para>becomes
</para>
<programlisting><![CDATA[
for (int i = 0; i < table1.Rows.Count; i++)
{
    textBoxList[i].Click += new EventHandler(this.iri_Click);
    labelList[i].Location = new Point(10, i * 22 + 50);
    labelList[i].Click += new EventHandler(this.label_Click);
    textBoxList[i].Location = new Point(150, i * 22 + 50);
    describeForm.Controls.Add(labelList[i]);
    describeForm.Controls.Add(textBoxList[i]);
]]></programlisting>
</listitem>
  <listitem>Then we need to add the EventHandler method. Add the following to the ExtendedStringHandler Class:
<programlisting><![CDATA[
public void label_Click(object sender, EventArgs e)
  {
      int labelNum = 0;

      for (int i = 0; i < labelList.Count; i++)
      {
          if (sender == labelList[i])
          {
              labelNum = i;
              break;
          }
      }

      Object o = describeDataSet.DataTable1.Rows[labelNum][0];
      if (o is SqlExtendedString)
      {
          SqlExtendedString se = (SqlExtendedString)o;
          ExtendedStringHandler seHandler = new ExtendedStringHandler(se, ParentConnection);
          seHandler.displayData();
      }
      else if (o is SqlRdfBox)
      {
          //doesn't do anything at the moment
      }
  }
]]></programlisting>
<para>
If you compare this method to the EventHandler for the values, iri_Click, you will see that it is basically
the same. The only difference is that it uses the property element from the data table rather than value.
</para>
</listitem>
  <listitem>Finally, to make it clear that the labels are now active links, we will change the label colour
to blue and underline them.
<programlisting><![CDATA[
 propertyLabel.Text = getLabelText(row[0]);
 propertyLabel.AutoEllipsis = true;
 propertyLabel.AutoSize = false;
 propertyLabel.Width = 130;
 propertyLabel.TextAlign = ContentAlignment.MiddleRight;
]]></programlisting>
<para>becomes:
</para>
<programlisting><![CDATA[
propertyLabel.Text = getLabelText(row[0]);
propertyLabel.ForeColor = Color.Blue;
propertyLabel.Font = new Font(propertyLabel.Font.FontFamily, propertyLabel.Font.Size, propertyLabel.Font.Style | FontStyle.Underline, propertyLabel.Font.Unit);
propertyLabel.AutoEllipsis = true;
propertyLabel.AutoSize = false;
propertyLabel.Width = 130;
propertyLabel.TextAlign = ContentAlignment.MiddleRight;
]]></programlisting>
</listitem>
  <listitem>Build and run the application. You will see the familiar starting page. If you then select one
of the Customers you will notice the property labels now look like hyperlinks.
    <figure id="sparqlwinf21" float="1">
      <title>hyperlinks</title>
      <graphic fileref="ui/sparqlwinf21.png"/>
    </figure>
<para>If you click on one of the label hyperlinks you will see a new form showing detailed information about
the property which can itself be explored further by clicking on labels and values.
    <figure id="sparqlwinf22" float="1">
      <title>labels and values</title>
      <graphic fileref="ui/sparqlwinf22.png"/>
    </figure>
</para>
</listitem>
</orderedlist>
<para>These simple changes work up to a point but are not robust. If you explore the properties used by the
local Northwind graph you quickly find that the property details are not found. The application needs some
further changes to work consistently. The problem is finding the graph where the property information is
defined. The general handler for Extended Strings first checks the local Northwind graph,
http://example.com/Northwind, where the Northwind data is held, and then uses the IRI itself as the graph
and tries to load that dynamically. This is not working for information about the Northwind properties.
These properties are defined in the Northwind ontology, http://demo.openlinksw.com/schemas/northwind. We
have already had to find this graph when getting the short label name. We need to be able to associate the
property label with the graph where its definition is stored. Then we can search this graph for details
about the property when the label is clicked.
</para>
    <para><emphasis>Using the Graph Where the Property Label was Found to Find the Property Details</emphasis></para>
<orderedlist>
  <listitem>Create a new class, IRILabel, that inherits from System.Windows.Forms.Label.
<itemizedlist mark="bullet">
  <listitem>In the <emphasis>Solution Explorer</emphasis> right click on the RDFDemo project and select
<emphasis>Add</emphasis> then <emphasis>New Item</emphasis>.</listitem>
  <listitem>Add a new class called IRILabel.cs.
    <figure id="sparqlwinf23" float="1">
      <title>Add a new class</title>
      <graphic fileref="ui/sparqlwinf23.png"/>
    </figure>
</listitem>
</itemizedlist>
</listitem>
  <listitem>We need to reference System.Windows.Forms, System.Data and OpenLink.Data.Virtuoso so add
<programlisting><![CDATA[
using System.Windows.Forms;
using OpenLink.Data.Virtuoso;
using System.Data;
]]></programlisting>
<para>to the using block at the top of the class file. The class definition should look like this:
</para>
<programlisting><![CDATA[
class IRILabel : Label
]]></programlisting>
</listitem>
  <listitem>Paste the following code into the body of the class:
<programlisting><![CDATA[
SqlExtendedString SourceIRI;
String GraphUsed;
VirtuosoConnection ParentConnection;

public IRILabel(Object iri, List<String> graphList, VirtuosoConnection parentConnection)
{
    ParentConnection = parentConnection;
    if (iri is SqlExtendedString)
    {
        SourceIRI = (SqlExtendedString)iri;
        Text = this.getLabelText(graphList);
    }
    else
        Text = iri.ToString();
}

public SqlExtendedString iri
{
    get
    {
        return SourceIRI;
    }
}

public String graph
{
    get
    {
        return GraphUsed;
    }
}

private string getLabelText(List<String> graphList)
{
    string labelText = SourceIRI.ToString();
    Boolean foundLabel = false;
    VirtuosoDataAdapter getLabelAdapter = new VirtuosoDataAdapter();
    DataSet getLabelDataSet = new DataSet();

    //Try finding it in resources graph first
    foreach (String graph in graphList)
    {
        StringBuilder getLabelCommandText = new StringBuilder("sparql select * from <" + graph + "> where {<" + SourceIRI.ToString() + "> ?p ?o}");
        VirtuosoCommand getLabelCommand = new VirtuosoCommand(getLabelCommandText.ToString(), ParentConnection);
        getLabelAdapter.SelectCommand = getLabelCommand;

        try
        {
            getLabelAdapter.Fill(getLabelDataSet);
            foreach (DataRow getLabelRow in getLabelDataSet.Tables[0].Rows)
            {
                if (getLabelRow[0].ToString() == "http://www.w3.org/2000/01/rdf-schema#label")
                {
                    labelText = getLabelRow[1].ToString();
                    foundLabel = true;
                    break;
                }
            }
        }
        catch
        {
        }
        if (foundLabel)
        {
            GraphUsed = graph;
            break;
        }
    }

    // If we still have no label try the predicate itself as the graph
    if (!foundLabel)
    {
        GraphUsed = SourceIRI.ToString();
        StringBuilder getLabelCommandText = new StringBuilder("sparql define get:soft \"soft\" select * from <" + GraphUsed + "> where {<" + SourceIRI.ToString() + "> ?p ?o}");
        VirtuosoCommand getLabelCommand = new VirtuosoCommand(getLabelCommandText.ToString(), ParentConnection);
        getLabelAdapter.SelectCommand = getLabelCommand;
        try
        {
            getLabelAdapter.Fill(getLabelDataSet);
            foreach (DataRow getLabelRow in getLabelDataSet.Tables[0].Rows)
            {
                if (getLabelRow[0].ToString() == "http://www.w3.org/2000/01/rdf-schema#label")
                {
                    labelText = getLabelRow[1].ToString();
                    break;
                }
            }
        }
        catch
        {
        }
    }
    return labelText;
}
]]></programlisting>
<para>Notice that the getLabelText method has been moved into this new class and is now called from the
constructor. When the IRILabel is constructed the label text is found using the list of graphs provided to
the constructor. The graph containing the label is noted. We need to alter ExtendedStringHandler so that
the labels are the new IRILabel type and so that the correct information is supplied to the constructor.
</para>
  </listitem>
  <listitem>Change the labelList member variable declaration so it looks like this:
<programlisting><![CDATA[
List<IRILabel> labelList = new List<IRILabel>();
]]></programlisting>
  </listitem>
  <listitem>Each propertyLabel created must be the new IRILabel type so the line:
<programlisting><![CDATA[
Label propertyLabel = new Label();
]]></programlisting>
<para>becomes:
</para>
<programlisting><![CDATA[
IRILabel propertyLabel = new IRILabel(row[0], graphList, ParentConnection);
]]></programlisting>
  </listitem>
  <listitem>As getLabelText is now called by the IRILabel constructor we can remove the line:
<programlisting><![CDATA[
propertyLabel.Text = getLabelText(row[0]);
]]></programlisting>
<para>from describeData in ExtendedStringHandler.
</para>
  </listitem>
  <listitem>Now we modify the label_Click EventHandler so that it uses the graph information. Replace the
existing method with:
<programlisting><![CDATA[
public void label_Click(object sender, EventArgs e)
  {
      int labelNum = 0;

      for (int i = 0; i < labelList.Count; i++)
      {
          if (sender == labelList[i])
          {
              labelNum = i;
              break;
          }
      }

      SqlExtendedString se = labelList[labelNum].iri;
      ExtendedStringHandler seHandler = new ExtendedStringHandler(se, ParentConnection, labelList[labelNum].graph);
          seHandler.displayData();

  }
]]></programlisting>
  </listitem>
  <listitem>Note that this method uses a new constructor for the ExtendedStringHandler that takes the graph
as an additional argument. We need to add this new constructor.
<programlisting><![CDATA[
public ExtendedStringHandler(SqlExtendedString iri, VirtuosoConnection parentConnection, String graph)
  {
      ParentConnection = parentConnection;
      if (iri.IriType == SqlExtendedStringType.IRI)
      {
          ParentIRI = iri;
          isIRI = true;
          DescribeCommandSimple = new StringBuilder("sparql select * from <http://example.com/Northwind> where {<" + iri.ToString() + "> ?p ?o}");
          DescribeCommandGeneral = new StringBuilder("sparql define get:soft " + '"'.ToString() + "soft" + '"'.ToString() + " select * from <" + graph + "> where { <" + iri.ToString() + "> ?p ?o }");
      }
  }
]]></programlisting>
<para>This new constructor uses the supplied graph to build the alternative sparql select statement that
looks for the details about the supplied IRI. With these changes in place the application will find the
description of the Northwind properties.
</para>
  </listitem>
  <listitem>Build and run. As you explore the data you will see that you can find descriptions of the
properties used to describe the entities in the Northwind dataset:
    <figure id="sparqlwinf24" float="1">
      <title>Northwind dataset</title>
      <graphic fileref="ui/sparqlwinf24.png"/>
    </figure>
  </listitem>
</orderedlist>
    </sect3>
    </sect2>
  </sect1>

<sect1 id="installcrweb">
  <title>Creating a Web Browser Application to Access RDF Data Using The Virtuoso ADO.Net Provider</title>
<para>This section will guide you through creating first a Web Service that exposes RDF data from Virtuoso
and then a simple web browser application that consumes the Web Service and allowing you to access and
explore the RDF data by clicking on dereferenceable <link linkend="rdfiriidtype">IRIs</link>.
</para>
<sect2 id="installcrwebintro">
      <title>Pre-requisites</title>
<orderedlist>
  <listitem>The example assumes that you have a local Virtuoso server with the Northwind demo database
installed. If the demo database is not already installed then download the <ulink url="http://download.openlinksw.com/packages/5.0/virtuoso/demo_dav.vad">demo database VAD package</ulink>
(demo_dav.vad) and install it. The VAD package will create a new database in Virtuoso called demo
containing the familiar Northwind tables. It will also creates <link linkend="rdfviewsrdbms">Linked Data Views</link> of the Northwind tables.
In the example we assume the database is accessible on a hostname of "demo.openlinksw.com" on the
default port 80, where an actually live instance of the Virtuoso Demo database is hosted. Users would
use the appropriate hostname and port number of their Virtuoso installation to create the sample
application, and would be would be example.com for a default installation or whatever the <link linkend="ini_URIQA">URIQA DefaultHost</link>
Virtuoso configuration parameter is set to when the demo database VAD package is installed.
  </listitem>
  <listitem>The Virtuoso ADO.Net provider for .Net 3.5 and the Entity Framework.</listitem>
  <listitem>Microsoft Visual Studio 2008</listitem>
  <listitem>The Virtuoso <ulink url="http://s3.amazonaws.com/opldownload/uda/vad-packages/6.3/virtuoso/cartridges_dav.vad">Cartridges VAD package</ulink>.</listitem>
</orderedlist>
    </sect2>
    <sect2 id="installcrwebcrserv">
      <title>Creating the Web Service</title>
    <para><emphasis>Step 1 - Create a view of the RDF data</emphasis></para>
<para>To create a view of the customers in the Northwind first open the Virtuoso Conductor and log in as
dba. Then open iSQL from the menu on the left and execute the following statement.
</para>
<programlisting><![CDATA[
create view Demo.demo.sparqlview as
sparql
select distinct ?s  from <http://example.com/Northwind>
where {?s a <http://demo.openlinksw.com/schemas/northwind#Customer>}
]]></programlisting>
    <para>Note:</para>
    <itemizedlist mark="bullet">
      <listitem>If the view is added to the Visual Studio project as user "demo" (or any other than "dba'),
then it must be ensured that the "SPARQL_SELECT" and "SPARQL_SPONGE" roles are assigned to this user, which
can be done via the Virtuoso Conductor in the "System Admin" -> "User Accounts" tab. </listitem>
      <listitem>Execute permissions will also need to be granted to the following procedure:
<programlisting><![CDATA[
grant execute on DB.DBA.RDF_MAKE_LONG_OF_SQLVAL to "demo"
]]></programlisting>
      </listitem>
    </itemizedlist>
        <figure id="sparqlwinf25" float="1">
      <title>create a view</title>
      <graphic fileref="ui/sparqlwinf25.png"/>
    </figure>
    <para><emphasis>Step 2 - Create the Visual Studio Project and Add the Model</emphasis></para>
<orderedlist>
  <listitem>Open <emphasis>Visual Studio</emphasis> and create a new <emphasis>ASP .NET Web Application
</emphasis> called RDFWebDemo.
    <figure id="sparqlwinf26" float="1">
      <title>create new application</title>
      <graphic fileref="ui/sparqlwinf26.png"/>
    </figure>
</listitem>
  <listitem>Right click RDFWebDemo in the <emphasis>Solution Explorer</emphasis> and add a new
<emphasis>ADO.NET Entity Data Model</emphasis> called Model1.edmx.
This will open the Entity Data Model Wizard.</listitem>
  <listitem>Choose <emphasis>Generate From Database</emphasis> and click <emphasis>Next</emphasis>.</listitem>
  <listitem>Set up a connection to the Demo database on your local Virtuoso Server, select
<emphasis>Yes, include the sensitive data in the connection string</emphasis> and set the name of the
entities to DemoEntities. Click <emphasis>Next</emphasis>.</listitem>
  <listitem>On the <emphasis>Choose Your Database Objects</emphasis> page expand <emphasis>Views</emphasis>
and select sparqlview. Check that the Model Namespace is DemoModel and click Finish.
    <figure id="sparqlwinf27" float="1">
      <title>Model Namespace</title>
      <graphic fileref="ui/sparqlwinf27.png"/>
    </figure>
</listitem>
</orderedlist>
<para>
</para>
    <para><emphasis>Step 3 - Add the Web Service</emphasis></para>
<orderedlist>
  <listitem>Right click RDFWebDemo in the <emphasis>Solution Explorer</emphasis> and add a new
<emphasis>ADO.NET Data Service</emphasis> called WebDataService1.svc. Click <emphasis>Add</emphasis>.</listitem>
  <listitem>In the class definition of WebDataService1 in the newly created file WebDataService1.svc.cs replace /* TODO: put your data source class name here */ with the name of our model, DemoEntities.
<programlisting><![CDATA[
public class WebDataService1 : DataService<DemoEntities>
]]></programlisting>
</listitem>
  <listitem>In the InitializeService method add the line:
<programlisting><![CDATA[
config.SetEntitySetAccessRule("*", EntitySetRights.All);
]]></programlisting>
<para>The method should look like this:
</para>
<programlisting><![CDATA[
 public static void InitializeService(IDataServiceConfiguration config)
   {
       // TODO: set rules to indicate which entity sets and service operations are visible, updatable, etc.
       // Examples:
       // config.SetEntitySetAccessRule("MyEntityset", EntitySetRights.AllRead);
       // config.SetServiceOperationAccessRule("MyServiceOperation", ServiceOperationRights.All);

       config.SetEntitySetAccessRule("*", EntitySetRights.All);
   }
]]></programlisting>
</listitem>
</orderedlist>
    <para><emphasis>Step 4 - Compile and Run</emphasis></para>
<para>Hit <emphasis>F5</emphasis> to compile and run the service. Select <emphasis>OK</emphasis> when
prompted to enable debugging. The default browser will be launched showing a page like:
</para>
<programlisting><![CDATA[
  <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
- <service xml:base="http://example.com/WebDataService1.svc/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xmlns="http://www.w3.org/2007/app">
- <workspace>
  <atom:title>Default</atom:title>
- <collection href="sparqlview">
  <atom:title>sparqlview</atom:title>
  </collection>
  </workspace>
  </service>
]]></programlisting>
<para>The service is now running.
</para>
<para>Note the address on which the service is made available. You will need to know this when creating
the app to consume the service. Look in the Address Bar of the browser. It will be something like:
http://example.com/WebDataService1.svc/
</para>
    </sect2>
    <sect2 id="installcrbrappl">
      <title>Creating the Browser Application</title>
<para><emphasis>Step 1 - Create the Visual Studio Project.</emphasis></para>
<orderedlist>
  <listitem>Open <emphasis>Visual Studio</emphasis> and create a new
<emphasis>ASP.NET Web Application</emphasis> called RDFWebApp.
    <figure id="sparqlwinf28" float="1">
      <title>New Web Application</title>
      <graphic fileref="ui/sparqlwinf28.png"/>
    </figure>
</listitem>
  <listitem>Create client side entities with datasvcutil.exe
<itemizedlist mark="bullet">
  <listitem>Open a command prompt.</listitem>
  <listitem>Navigate to *C:\WINDOWS\Microsoft.NET\Framework\v3.5*.</listitem>
  <listitem>Generate the client classes using the following command:
<programlisting><![CDATA[
datasvcutil.exe /uri:http://example.com/WebDataService1.svc /out:DemoEntities.cs
]]></programlisting>
<para>Note the address of the service - you may need to change the port number to
match the one seen in the address at the end of Step 4 in Creating the Web Service.
</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>Add the classes to RDFWebApp.
<itemizedlist mark="bullet">
  <listitem>Right click RDFWebApp</listitem>
  <listitem>Choose to add an existing item and add c:\WINDOWS\Microsoft.NET\Framework\v3.5\DemoEntities.cs.</listitem>
</itemizedlist>
</listitem>
  <listitem>Add a reference to System.Data.Services.Client to the project.</listitem>
</orderedlist>
<para>
</para>
    <para><emphasis>Step 2 - Display the contents of sparqlview as a table on the page</emphasis></para>
<para>To display the RDF data on the web page we create a table with a row for each item in sparqlview.
We then use each IRI from sparqlview to create a hyperlink. The hyperlinks are displayed in the table
cells. To do this add the following block of code to the page_load method in Default.aspx.cs.
</para>
<programlisting><![CDATA[
 DemoModel.DemoEntities svc = new DemoModel.DemoEntities(new Uri("http://example.com/WebDataService1.svc"));

  var query = svc.sparqlview;
  Table iriTable = new Table();
  this.Controls.Add(iriTable);

  foreach (DemoModel.sparqlview sv in query)
  {
      TableRow tRow = new TableRow();
      iriTable.Rows.Add(tRow);
      TableCell tCell = new TableCell();
      tRow.Cells.Add(tCell);
      HyperLink h = new HyperLink();
      h.Text = sv.s;
      h.NavigateUrl = sv.s;
      tCell.Controls.Add(h);
  }
]]></programlisting>
<para>Note the address of the service in the first line - you may need to change the port number to match
the one seen in the address at the end of Step 4 in Creating the Web Service.
</para>
<para>Compile and run RDFWebApp (ensuring that the service created above is still running). This will
launch a browser and display the IRIs from sparqlview as a list of hyperlinks.
</para>
    <figure id="sparqlwinf29" float="1">
      <title>list of hyperlinks</title>
      <graphic fileref="ui/sparqlwinf29.png"/>
    </figure>
<para>With the <ulink url="http://s3.amazonaws.com/opldownload/uda/vad-packages/6.3/virtuoso/cartridges_dav.vad">Cartridges VAD package</ulink> installed in Virtuoso, clicking on these
links will take you to a description page of the referenced resource. The description page is created
using <ulink url="http://virtuoso.openlinksw.com/Whitepapers/html/vdld_html/VirtDeployingLinkedDataGuide_Glossary.html#mozTocId13075">description.vsp</ulink>.
</para>
    <figure id="sparqlwinf30" float="1">
      <title>Description page</title>
      <graphic fileref="ui/sparqlwinf30.png"/>
    </figure>
    </sect2>
    <sect2 id="installcrwebiis"><title>Deploy With IIS</title>
<para>To create and test this simple Web Service we have used the Visual Studio Development Server. This
section describes how to deploy the service using IIS.
</para>
        <sect3 id="installcrwebiiswebs"><title>Web Service</title>
<para>To deploy the service using IIS:
</para><itemizedlist mark="bullet">
  <listitem>Open the RDFWebDemo project in Visual Studio, go to the <emphasis>Project</emphasis> menu
and select RDFWebDemo <emphasis>Properties</emphasis>.</listitem>
  <listitem>Select the <emphasis>Web</emphasis> tab and scroll down to the <emphasis>Servers</emphasis>
section. Select <emphasis>Use local IIS Server</emphasis>. The project URL defaults to using localhost.</listitem>
  <listitem>Click the <emphasis>Create Virtual Directory</emphasis> button then check that the Service works on localhost.</listitem>
  <listitem>Build the project then start without debugging (ctrl F5).</listitem>
</itemizedlist>
<para>The start page that you see when you test the service will look the same as before but the address
in the browser bar will be something like http://example.com/RDFWebDemo1/WebDataService1.svc/. You can now
access your service remotely using the hostname or IP address of your server.
</para>
<para>If at this point you get an Access is denied error, 401.3, then you will need to add the Internet
Guest Account (IUSR_XXX where XXX is your computer name) to the users allowed to access the folder
containing the RDFWebDemo project.
</para>
        </sect3>
        <sect3 id="installcrwebiisweba"><title>Web Application</title>
<para>You will now need to modify RDFWebApp to access the service at the new address. At the same time
we will also change RDFWebApp so that it too is deployed using IIS
</para>
<itemizedlist mark="bullet">
  <listitem>Open The RDFWebApp project in Visual Studio.</listitem>
  <listitem>Go to the <emphasis>Project</emphasis> menu and select RDFWebApp <emphasis>Properties</emphasis>.</listitem>
  <listitem>Select the <emphasis>Web</emphasis> tab and scroll down to the <emphasis>Servers</emphasis>
section. Select <emphasis>Use local IIS Server</emphasis>. The project URL defaults to using localhost.</listitem>
  <listitem>Click the <emphasis>Create Virtual Directory</emphasis> button. The web application will then run on the local IIS.
<programlisting><![CDATA[
DemoModel.DemoEntities svc = new DemoModel.DemoEntities(new Uri("http://example.com/WebDataService1.svc"));
]]></programlisting>
<para>to
</para>
<programlisting><![CDATA[
DemoModel.DemoEntities svc = new DemoModel.DemoEntities(new Uri("http://example.com/RDFWebDemo/WebDataService1.svc/"));
]]></programlisting>
</listitem>
  <listitem>To reference the web service running on IIS you will need to edit Default.aspx.cs. Change </listitem>
  <listitem>Build the project then start without debugging (ctrl F5).</listitem>
</itemizedlist>
<para>
The web application is accessible on http://example.com/RDFWebApp/Default.aspx and can also be accessed using
the hostname or IP address of you server e.g. http://192.168.7.129/RDFWebApp/Default.aspx
</para>
    <figure id="sparqlwinf31" float="1">
      <title>Default.aspx</title>
      <graphic fileref="ui/sparqlwinf31.png"/>
    </figure>
    </sect3>
    <para><emphasis>Next Steps</emphasis></para>
<para>The next example shows you how to quickly create an ADO.Net Data Service that exposes RDF data in
Virtuoso and how to create a basic Web application to consume that service. The next step is to
<link linkend="installsilver">create a Silverlight Application to consume the same service</link>.
</para>
    </sect2>
  </sect1>


<sect1 id="installsilver"><title>Creating a Silverlight Application to consume the service</title>
<para>This section will guide you through creating an application for Silverlight that will consume
the ADO.Net Data Service created in <link linkend="installcrweb">Creating a Web Browser Application to Access RDF Data Using The
Virtuoso ADO.Net Provider.</link>
</para>
      <sect2 id="installsilverpreq">
        <title>Pre-requisites</title>
<orderedlist>
  <listitem>The <ulink url="http://www.microsoft.com/downloads/details.aspx?FamilyId=c22d6a7b-546f-4407-8ef6-d60c8ee221ed&amp;displaylang=en">Microsoft Silverlight 2 Tools for Visual Studio 2008 SP1</ulink></listitem>
  <listitem>The ADO.Net Data Service created in <link linkend="installcrweb">Creating a Web Browser Application to Access RDF Data Using The
Virtuoso ADO.Net Provider.</link></listitem>
  <listitem>The Visual Studio project used to create the ADO.Net Data Service.</listitem>
</orderedlist>
    </sect2>
    <sect2 id="installsilvercrser">
        <title>Creating the Application for Silverlight.</title>
<orderedlist>
  <listitem>Open the ADO.Net Data Service project in <emphasis>Visual Studio</emphasis></listitem>
  <listitem>In the <emphasis>Solution Explorer</emphasis> right click on the RDFWebDemo solution and add a new Project. </listitem>
  <listitem>In the <emphasis>Add New Project</emphasis> dialog select
<emphasis>Silverlight Application</emphasis> and click <emphasis>OK</emphasis>. This will open
the <emphasis>Add Silverlight Application</emphasis> dialog.
      <figure id="sparqlwinf32" float="1">
      <title>Add Silverlight Application</title>
      <graphic fileref="ui/sparqlwinf32.png"/>
    </figure>
  </listitem>
  <listitem>Select <emphasis>Link this Silverlight Control into an existing Web Site</emphasis> and make
sure the Web Site selected is RDFWebDemo. Select
<emphasis>Add a test page that references the application</emphasis> and <emphasis>Make it the start
page</emphasis>.
      <figure id="sparqlwinf33" float="1">
      <title>Add a test page</title>
      <graphic fileref="ui/sparqlwinf33.png"/>
    </figure>
  </listitem>
  <listitem>In Solution Explorer, select RDFWebDemo, open the Project menu and select Properties. </listitem>
  <listitem>Select the <emphasis>Web</emphasis> tab, and select <emphasis>Specific Page</emphasis>
in the <emphasis>Start Action</emphasis> section. Click on the ellipsis and select
SilverlightApplication1TestPage.html as the start page. </listitem>
  <listitem>Add a reference to the data service. In the <emphasis>Solution Explorer</emphasis> right click
on SilverlightApplication1 and select <emphasis>Add Service Reference</emphasis></listitem>
  <listitem>In the <emphasis>Add Service Reference</emphasis> dialog click the <emphasis>Discover</emphasis>
button. Your ADO.Net Data Service should appear in the Address box and the Services box. </listitem>
  <listitem>Select the service and click <emphasis>OK</emphasis>. ServiceReference1 will now be added to
the ServiceReferences. </listitem>
  <listitem>Open page.xaml.cs and add references to the service and to the System.Data.Services.Client
assembly by adding the following using statements at the top of the file:
  <programlisting><![CDATA[
using System.Data.Services.Client;
using SilverlightApplication1.ServiceReference1;
]]></programlisting>
  </listitem>
  <listitem>We need at create a data service context to reference the data from the service and to load data
from the view, sparqlview, exposed by the service. Add the following lines to the page constructor after
InitializeComponent()
<programlisting><![CDATA[
DataServiceContext svcCtx = new DataServiceContext(new Uri("WebDataService1.svc", UriKind.Relative));
svcCtx.BeginExecute<sparqlview>(new Uri("sparqlview", UriKind.Relative), loadSCallback, svcCtx);
]]></programlisting>
  </listitem>
  <listitem>Add the loadSCallback method to the page class. The method loads the data from sparqlview and
puts it in a List. This List populates a list box on the page.
<programlisting><![CDATA[
private void loadSCallback(IAsyncResult asyncResult)
{   List<Uri> uList = new List<Uri>();
    DataServiceContext ctx = asyncResult.AsyncState as DataServiceContext;
    foreach (sparqlview sv in ctx.EndExecute<sparqlview>(asyncResult))
     uList.Add(new Uri(sv.s));
    listBox1.DataContext = uList;
}
]]></programlisting>
  </listitem>
  <listitem>Add the list box to the page. In the <emphasis>Solution Explorer</emphasis> double click on
page.xaml to open it in the editor. Add the following code between the &lt;grid&gt; and &lt;/grid&gt; tags.
<programlisting><![CDATA[
<ListBox x:Name="listBox1"
    HorizontalAlignment="Stretch"
    Margin="25,8,26,-78" Grid.RowSpan="1"
    Grid.Row="0" VerticalAlignment="Stretch"
    ItemsSource="{Binding Mode=OneWay}" >
    <ListBox.ItemTemplate>
        <DataTemplate>
            <StackPanel x:Name="DisplayListData"
             Orientation="Horizontal"
             VerticalAlignment="Bottom"
             Margin="5" >
                <HyperlinkButton
                 Content ="{Binding}"
                 NavigateUri="{Binding}"
                 Margin="5,0,0,0"
                 VerticalAlignment="Bottom"
                 HorizontalAlignment="Left"
                 FontSize="12">
                </HyperlinkButton>
            </StackPanel>
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>
]]></programlisting>
  </listitem>
  <listitem>Build the Silverlight application and launch without debugging using <emphasis>Ctrl F5</emphasis>.
This will launch the browser and open SilverlightApplication1TestPage.aspx.
        <figure id="sparqlwinf34" float="1">
      <title>SilverlightApplication1TestPage.aspx</title>
      <graphic fileref="ui/sparqlwinf34.png"/>
    </figure>
  </listitem>
</orderedlist>
<para>
Clicking on one of the IRIs will open the page using description.vsp.
</para>
            <figure id="sparqlwinf35" float="1">
      <title>using description.vsp</title>
      <graphic fileref="ui/sparqlwinf35.png"/>
    </figure>
    </sect2>
</sect1>

<sect1 id="installnetriadd"><title>Creating A Simple .NET RIA Services Application To Display Data
From Virtuoso</title>
<para>.NET RIA Services is a new framework from Microsoft that simplifies the development of n-tier web
applications. A typical application will consist of a presentation layer, application logic and a data
access layer. In these examples a combination of Silverlight 3 and .NET RIA Services will provide the
presentation layer and application layer while the data will reside in Virtuoso and be accessed using
the Virtuoso ADO.NET provider. The first example demonstrates how to display data from the Employee
table in the Demo database in a grid on a web page. The second example shows how to display IRIs from
the Linked Data Views of the demo data. The IRIs are used to create hyperlinks that are the starting point
for exploring the linked data.
</para>
      <sect2 id="installnetriaddpreq">
        <title>Pre-requisites</title>
<orderedlist>
  <listitem>The example assumes that you have a local Virtuoso server with the Northwind demo database
installed. If the demo database is not already installed then download the demo database VAD package
(demo_dav.vad) and install it. The VAD package will create a new database in Virtuoso called demo
containing the familiar Northwind tables. It will also creates Linked Data Views of the Northwind tables.
In the example we assume the database is accessible on a hostname of "demo.openlinksw.com" on the
default port 80, where an actually live instance of the Virtuoso Demo database is hosted. Users
would use the appropriate hostname and port number of their Virtuoso installation to create the
sample application, and would be would be example.com for a default installation or whatever
the URIQA DefaultHost Virtuoso configuration parameter is set to when the demo database VAD package
is installed.</listitem>
  <listitem>The Virtuoso ADO.Net provider for .Net 3.5 and the Entity Framework.</listitem>
  <listitem>Microsoft Visual Studio 2008</listitem>
  <listitem>The Virtuoso <ulink url="http://s3.amazonaws.com/opldownload/uda/vad-packages/6.3/virtuoso/cartridges_dav.vad">Cartridges VAD package</ulink>.</listitem>
  <listitem><ulink url="http://www.microsoft.com/downloads/details.aspx?familyid=9442b0f2-7465-417a-88f3-5e7b5409e9dd&amp;displaylang=en">Silverlight 3 Tools for Visual Studio 2008 SP1</ulink>.</listitem>
  <listitem><ulink url="http://www.microsoft.com/downloads/details.aspx?FamilyID=76bb3a07-3846-4564-b0c3-27972bcaabce&amp;displaylang=en">Microsoft .NET RIA Services July 2009 Preview</ulink>.</listitem>
</orderedlist>
    </sect2>
    <sect2 id="installnetriaddcrser">
        <title>Creating the Application</title>
<para><emphasis>Step 1 - Create the Visual Studio Projects.</emphasis></para>
<orderedlist>
  <listitem>Open <emphasis>Visual Studio</emphasis> and create a new <emphasis>Silverlight Application</emphasis> project. Call the project DemoApplication.</listitem>
  <listitem>In the New Silverlight Application dialog ensure that <emphasis>Enable .NET RIA Services</emphasis> is checked. Click the <emphasis>OK</emphasis> button.
      <figure id="ria1" float="1">
        <title>.NET RIA Services Application</title>
        <graphic fileref="ui/ria1.png"/>
      </figure>
  </listitem>
</orderedlist>
  <para>At this point a skeleton solution is created that consists of a client project called DemoApplication
and a server project called DemoApplication.Web. This application will use data from the Virtuoso database.
We add the data and its schema to the application by adding an ADO.NET entity data model to the server
project.</para>
<para><emphasis>Step 2 -  Add the Data Model</emphasis></para>
<orderedlist>
  <listitem>Right click the server project in the <emphasis>Solution Explorer</emphasis> and
<emphasis>Add New Item</emphasis>. In the dialog box select <emphasis>ADO.NET Entity Data Model</emphasis>
and call it demo.edmx. Click the <emphasis>Add</emphasis> button. This will open the
<emphasis>Entity Data Model Wizard</emphasis>.</listitem>
  <listitem>Choose <emphasis>Generate From Database</emphasis> and click <emphasis>Next</emphasis>.</listitem>
  <listitem>Set up a connection to the Demo database on your local Virtuoso Server, select
<emphasis>Yes, include the sensitive data in the connection string</emphasis> and set the name of the
entities to DemoEntities. Click <emphasis>Next</emphasis>.</listitem>
  <listitem>On the <emphasis>Choose Your Database Objects</emphasis> page expand <emphasis>Tables</emphasis>
and select Employees. Check that the Model Namespace is DemoModel and click <emphasis>Finish</emphasis>.</listitem>
</orderedlist>
      <figure id="ria2" float="1">
        <title>.NET RIA Services Application</title>
        <graphic fileref="ui/ria2.png"/>
      </figure>
  <para>We want to make the entities in the model available to both the client and server parts of the
solution. To do this we need to add a DomainService to the solution. However, to make the entities from
the data model available to the domain service we must first build the solution.</para>
<para><emphasis>Step 3 - Add a Domain Service.</emphasis></para>
<orderedlist>
  <listitem>First build the solution.</listitem>
  <listitem>Right click the server project in the <emphasis>Solution Explorer</emphasis> and
<emphasis>Add New Item</emphasis>. In the dialog box choose <emphasis>Domain Service Class</emphasis>
from the Templates pane and call it EmployeeService.cs. Click <emphasis>Add</emphasis>. This will open the
<emphasis>Add New Domain Service Class</emphasis> dialog.</listitem>
  <listitem>The entities from the model we have just added to the project are listed under
<emphasis>Entities</emphasis>. Tick the box next to Employees. and click OK.</listitem>
</orderedlist>
      <figure id="ria3" float="1">
        <title>.NET RIA Services Application</title>
        <graphic fileref="ui/ria3.png"/>
      </figure>
<para>This will create the DomainService class and generated code in both the client and server parts of
the application. The Silverlight client can now interact with the data through the DomainContext class
in the client project. At this point you need to build the solution again.
</para>
<para><emphasis>Step 4 -  Display The Data</emphasis></para>
<orderedlist>
  <listitem>From the <emphasis>Silverlight XAML Controls</emphasis> in the <emphasis>Toolbox</emphasis>
drag a <emphasis>DataGrid</emphasis> between the &lt;Grid&gt; &lt;/Grid&gt; tags on MainPage.xaml in the client. Call the grid EmployeeGrid.
<programlisting><![CDATA[
<data:DataGrid Name="EmployeeGrid"></data:DataGrid>
]]></programlisting>
</listitem>
  <listitem>Instantiate the DomainContext to get the list of employees and add them to the grid by
adding code to MainPage.xaml.cs so it looks like this:
<programlisting><![CDATA[
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;
using System.Windows.Shapes;
using DemoApplication.Web;
using System.Windows.Ria.Data;

namespace DemoApplication
{
    public partial class MainPage : UserControl
    {
        private EmployeeContext _employeeContext = new EmployeeContext();
        public MainPage()
        {
            InitializeComponent();
            LoadOperation<Employees> LoadOp =
                this._employeeContext.Load(this._employeeContext.GetEmployeesQuery());
            this.EmployeeGrid.ItemsSource = LoadOp.Entities;
        }
    }
}
]]></programlisting>
</listitem>
  <listitem>Build and run the application. Internet Explorer will be launched and you will see the data
displayed on the page as a grid.
</listitem>
</orderedlist>
      <figure id="ria4" float="1">
        <title>.NET RIA Services Application</title>
        <graphic fileref="ui/ria4.png"/>
      </figure>
   </sect2>
   <sect2 id="installnetriaddcrdf">
     <title>Displaying RDF Data</title>
     <para>One advantage of using Virtuoso as the data store is the seamless way in which we can use
this use this application to display dereferencable IRIs and explore RDF linked data.
     </para>
     <para>The Virtuoso SPASQL interface allows RDF data in the Virtuoso Quad store to be queried
using SPARQL from any SQL interface by simply prefixing the SPARQL query with the keyword SPARQL.
We will use the SPASQL interface to create a view containing the IRIs of the Employees in the
the Demo RDF data in Virtuoso.
     </para>
<para><emphasis>Step 1 -  Create the View in Virtuoso</emphasis></para>
<orderedlist>
  <listitem>Open the Virtuoso Conductor.</listitem>
  <listitem>In isql execute the following statement. Remember to use the appropriate hostname and port
number of your Virtuoso installation, typically example.com for a default installation or whatever
the <link linkend="ini_URIQA">URIQA DefaultHost</link> Virtuoso configuration parameter was set to when
the demo database VAD package was installed.
<programlisting><![CDATA[
CREATE VIEW Demo.demo.sparqlview as
SPARQL
PREFIX nwind: <http://demo.openlinksw.com/schemas/northwind#>
SELECT DISTINCT  ?s
FROM <http://demo.openlinksw.com/Northwind>
WHERE
  {
    ?s a nwind:Employee
  }
]]></programlisting>
</listitem>
</orderedlist>
<para><emphasis>Step 2 -  Modify the Solution To use the View</emphasis></para>
<orderedlist>
  <listitem>Delete the existing Employee model and add a new one that comprises this new view.
    <figure id="ria5" float="1">
      <title>.NET RIA Services Application</title>
      <graphic fileref="ui/ria5.png"/>
    </figure>
  </listitem>
  <listitem>Delete the DomainService. Build the solution and add a new DomainService called
EmployeeService. Select the sparqlview entity. Build the solution.
    <figure id="ria6" float="1">
      <title>.NET RIA Services Application</title>
      <graphic fileref="ui/ria6.png"/>
    </figure>
  </listitem>
 <listitem>Modify the code in mainpage.xaml.cs so it uses the sparqview entity. It should look like this:
<programlisting><![CDATA[
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;
using System.Windows.Shapes;
using DemoApplication.Web;
using System.Windows.Ria.Data;

namespace DemoApplication
{
    public partial class MainPage : UserControl
    {
        private EmployeeContext _employeeContext = new EmployeeContext();
        public MainPage()
        {
            InitializeComponent();
            LoadOperation<sparqlview> LoadOp =
                this._employeeContext.Load(this._employeeContext.GetSparqlviewQuery());
            this.EmployeeGrid.ItemsSource = LoadOp.Entities;
        }
    }
}
]]></programlisting>
</listitem>
  <listitem>Build and run the application. You will see a list of IRIs that identify the Northwind employees.
    <figure id="ria7" float="1">
      <title>.NET RIA Services Application</title>
      <graphic fileref="ui/ria7.png"/>
    </figure>
  </listitem>
</orderedlist>
<para>To realize the power of linked data we would now liked to begin exploring this data by clicking on
these IRIs.</para>
<para><emphasis>Step 3 - Make Hyperlinks From IRIs</emphasis></para>
<orderedlist>
  <listitem>Modify the DataGrid in MainPage.xaml to bind the IRI in each cell of the grid to a
Hyperlink button. We set the AutoGenerateColumns property of the DataGrid to False then add our
own Template for the column. MainPage.xaml should look like this:
<programlisting><![CDATA[
<UserControl xmlns:data="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Data"  x:Class="DemoApplication.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d" d:DesignWidth="640" d:DesignHeight="480">
  <Grid x:Name="LayoutRoot">
      <data:DataGrid Name="EmployeeGrid" AutoGenerateColumns="False">
            <data:DataGrid.Columns>
                <data:DataGridTemplateColumn Header="Employee">
                    <data:DataGridTemplateColumn.CellTemplate>
                        <DataTemplate>
                            <StackPanel x:Name="DisplayEmployeeData"
                                        Orientation="Horizontal"
                                        VerticalAlignment="Bottom"
                                        Margin="5" >
                                <HyperlinkButton Content ="{Binding s}"
                                                 NavigateUri="{Binding s}"
                                                 Margin="5,0,0,0"
                                                 VerticalAlignment="Bottom"
                                                 HorizontalAlignment="Left"
                                                 FontSize="12">
                                </HyperlinkButton>
                            </StackPanel>
                        </DataTemplate>
                    </data:DataGridTemplateColumn.CellTemplate>
                </data:DataGridTemplateColumn>
            </data:DataGrid.Columns>
        </data:DataGrid>
    </Grid>
</UserControl>
]]></programlisting>
</listitem>
  <listitem>If we build and run the project now each IRI in the list appears as a hyperlink.
    <figure id="ria8" float="1">
      <title>.NET RIA Services Application</title>
      <graphic fileref="ui/ria8.png"/>
    </figure>
</listitem>
  <listitem>Clicking on each of the links takes you to a new document that contains further links
to information about each Employee. The Demo dataset can be explored further by following the
dereferenceable IRIs in the description pages.
    <figure id="ria9" float="1">
      <title>.NET RIA Services Application</title>
      <graphic fileref="ui/ria9.png"/>
    </figure>
    <figure id="ria10" float="1">
      <title>.NET RIA Services Application</title>
      <graphic fileref="ui/ria10.png"/>
    </figure>
</listitem>
</orderedlist>
   </sect2>
   <sect2 id="installnetriaddcnext">
     <title>Next Steps</title>
     <para>The examples in this document show you how to simply display data in a browser using
Silverlight 3 and .NET RIA Services. See an <link linkend="installnetriavd">example</link> of a
more complicated application.</para>
   </sect2>
</sect1>

<sect1 id="installnetriavd"><title>Creating a .Net RIA Services Application That Will Update Virtuoso Data</title>
<para>This example demonstrates how data in Virtuoso can be updated from a Microsoft .NET RIA Services
application. The example is a continuation of the first example in <link linkend="installnetriadd">Creating a Simple .Net RIA Services
Application to Display Data From Virtuoso</link>.</para>
      <sect2 id="installnetriavdpreq">
        <title>Pre-requisites</title>
<orderedlist>
  <listitem>A working copy of the application created in <link linkend="installnetriadd">Creating a
Simple .Net RIA Services Application to Display Data From Virtuoso</link>.</listitem>
</orderedlist>
    </sect2>
    <sect2 id="installnetriavdcrser">
        <title>Creating the Application</title>
<para><emphasis>Step 1 - Add A New Domain Service Class</emphasis></para>
<para>The EmployeeService Domain Service Class was only used to display data so was created
read only. In this example we need to be able to update the data so we need to remove the read
only Domain Service Class and create a new on.</para>
<orderedlist>
  <listitem>In the <emphasis>Server Explorer</emphasis> right click EmployeeService and select <emphasis>Delete</emphasis></listitem>
  <listitem>Right click the server project and <emphasis>Add New Item</emphasis>. In the dialog box choose Domain Service Class from the Templates pane and again call it EmployeeService.cs. Click Add.</listitem>
  <listitem>Select the Employees entity and tick <emphasis>Enable editing</emphasis>. Also tick <emphasis>Generated associated classes for metadata</emphasis>.
      <figure id="riad1" float="1">
        <title>.NET RIA Services Application</title>
        <graphic fileref="ui/riad1.png"/>
      </figure>
  </listitem>
  <listitem>Update MainPage.xaml.cs to use EmployeeService2 the new domain service rather than EmployeeContext.</listitem>
</orderedlist>
  <para>We want to create a master detail style page. To do this we will use the DomainDataSourceComponent
from the Silverlight Components. But first we will add a pager so only 5 records are displayed at a time.</para>
<para><emphasis>Step 2 - Add a DataPager</emphasis></para>
<orderedlist>
  <listitem>Add two new namespaces to MainPage.xaml
<programlisting><![CDATA[
xmlns:riaControls="clr-namespace:System.Windows.Controls;assembly=System.Windows.Ria.Controls"
xmlns:ds="clr-namespace:DemoApplication.Web"
]]></programlisting>
  </listitem>
  <listitem>Use a DomainDataSource to provide the data to fill the grid. Add the following to
MainPage.xaml before the DataGrid.
<programlisting><![CDATA[
<riaControls:DomainDataSource x:Name="EmployeeDataSource"
                              QueryName="GetEmployeesQuery"
                              LoadSize="10"
                              AutoLoad="True">
    <riaControls:DomainDataSource.DomainContext>
        <ds:EmployeeService2/>
    </riaControls:DomainDataSource.DomainContext>
</riaControls:DomainDataSource>
]]></programlisting>
  </listitem>
  <listitem>Update the MainPage.xaml.cs code behind file. Using the DomainDataSource means you no
longer need to instantiate the context and load the grid in MainPage.xaml.cs so it becomes:
<programlisting><![CDATA[
public partial class MainPage : UserControl
{
    public MainPage()
    {
        InitializeComponent();
    }
}
]]></programlisting>
  </listitem>
  <listitem>Set the binding source of the DataGrid to the DomainDataSource
<programlisting><![CDATA[
<data:DataGrid MinHeight="100"  IsReadOnly="True" ItemsSource="{Binding Data, ElementName=EmployeeDataSource}" x:Name="DataGrid1"></data:DataGrid> />
]]></programlisting>
  </listitem>
  <listitem>Drag a DataPager form the tool box onto MainPage.xaml just after the DataGrid.
  </listitem>
  <listitem>Add a page size and binding element to the DataPager.
<programlisting><![CDATA[
<data:DataPager PageSize="5" Source="{Binding Data, ElementName=employeeDataSource}"
                      Margin="0,-1,0,0"></data:DataPager>
]]></programlisting>
  </listitem>
  <listitem>Build and run the application. The data should be displayed 5 rows at a time.
      <figure id="riad2" float="1">
        <title>.NET RIA Services Application</title>
        <graphic fileref="ui/riad2.png"/>
      </figure>
  </listitem>
</orderedlist>
  <para>We now need to add a DataForm to display the details.</para>
<para><emphasis>Step 3 - Add a DataForm</emphasis></para>
<orderedlist>
  <listitem>Add the following namespace to MainPage.xaml
<programlisting><![CDATA[
xmlns:dataForm="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Data.DataForm.Toolkit"
]]></programlisting>
</listitem>
  <listitem>Add the form to MainPage.xaml
<programlisting><![CDATA[
<dataForm:DataForm x:Name="dataForm1" Header="Employee Information"  AutoGenerateFields="False" AutoEdit="False" AutoCommit="False" CurrentItem="{Binding SelectedItem, ElementName=DataGrid1}" Margin="0,12,0,0">
   <dataForm:DataForm.EditTemplate>
       <DataTemplate>
           <StackPanel>
               <dataForm:DataField Label="Employee ID">
                   <TextBox Text="{Binding EmployeeID, Mode=TwoWay}" />
               </dataForm:DataField>
               <dataForm:DataField Label="First Name">
                   <TextBox Text="{Binding FirstName, Mode=TwoWay}" />
               </dataForm:DataField>
               <dataForm:DataField Label="Last Name">
                   <TextBox Text="{Binding LastName, Mode=TwoWay}" />
               </dataForm:DataField>
               <dataForm:DataField Label="Courtesy Title">
                   <TextBox Text="{Binding TitleOfCourtesy, Mode=TwoWay}" />
               </dataForm:DataField>
               <dataForm:DataField Label="Hire Date">
                   <TextBox Text="{Binding HireDate, Mode=TwoWay}" />
               </dataForm:DataField>
               <dataForm:DataField Label="Title">
                   <TextBox Text="{Binding Title, Mode=TwoWay}"  />
               </dataForm:DataField>
               <dataForm:DataField Label="Reports To">
                   <TextBox Text="{Binding ReportsTo, Mode=TwoWay}"  />
               </dataForm:DataField>
               <dataForm:DataField Label="Region">
                   <TextBox Text="{Binding Region, Mode=TwoWay}"  />
               </dataForm:DataField>
               <dataForm:DataField Label="Address">
                   <TextBox Text="{Binding Address, Mode=TwoWay}"  />
               </dataForm:DataField>
               <dataForm:DataField Label="City">
                   <TextBox Text="{Binding City, Mode=TwoWay}"  />
               </dataForm:DataField>
               <dataForm:DataField Label="Country Code">
                   <TextBox Text="{Binding CountryCode, Mode=TwoWay}"  />
               </dataForm:DataField>
               <dataForm:DataField Label="Postal Code">
                   <TextBox Text="{Binding PostalCode, Mode=TwoWay}"  />
               </dataForm:DataField>
                   </StackPanel>
       </DataTemplate>
   </dataForm:DataForm.EditTemplate>
 </dataForm:DataForm>
]]></programlisting>
</listitem>
  <listitem>Surround the DomainDataSource, DataGrid and DataForm with
<programlisting><![CDATA[
        <ScrollViewer BorderThickness="0"  VerticalScrollBarVisibility="Auto" Padding="12,0,12,0" Margin="-2">
            <StackPanel Margin="0,12,0,12" Orientation="Vertical" >
.
.
.
            </StackPanel>
        </ScrollViewer>
]]></programlisting>
</listitem>
  <listitem>Build and run the application. As each employee is selected the data form fill with their details
      <figure id="riad3" float="1">
        <title>.NET RIA Services Application</title>
        <graphic fileref="ui/riad3.png"/>
      </figure>
</listitem>
</orderedlist>
<para>By clicking on the pencil symbol in the top right hand corner the data in the form can be edited
but it is not propagated back to the database.</para>
   </sect2>
    <sect2 id="installnetriavdcrprup">
        <title>Propagate Updates to Virtuoso</title>
<orderedlist>
  <listitem>Add a 'Submit' button just after the DataForm in MainPage.xaml by adding the following code.
<programlisting><![CDATA[
<StackPanel Orientation="Horizontal" HorizontalAlignment="Right" Margin="0,12,0,0">
  <Button x:Name="submitButton" Width="75" Height="23"  Content="Submit"  Margin="4,0,0,0" Click="submitButton_Click"/>
</StackPanel>
]]></programlisting>
</listitem>
  <listitem>Handle the button click event in MainPage.xaml.cs by adding the following code:
<programlisting><![CDATA[
private void submitButton_Click(object sender, RoutedEventArgs e)
        {
            EmployeeDataSource.SubmitChanges();
        }
]]></programlisting>
</listitem>
  <listitem>Build and run the application. If you now edit data in the form and click the submit button
the data in Virtuoso will be updated.
      <figure id="riad4" float="1">
        <title>.NET RIA Services Application</title>
        <graphic fileref="ui/riad4.png"/>
      </figure>
</listitem>
</orderedlist>
   </sect2>
</sect1>


<sect1 id="clusterstcnf"><title>Cluster Installation and Configuration</title>

<!-- ======================================== -->
  <sect2 id="clusterstcnf7">
     <title>Virtuoso Elastic Cluster Installation &amp; Configuration -- Version 7.x</title>
     <para>These sections apply to Virtuoso as of version 7.x .</para>
       <sect3 id="clusterstcnfconf7what">
         <title>What</title>
         <para>Virtuoso 7 and later versions can be configured in Elastic scale out cluster mode. The data is sharded in a
         	large number of self-contained partitions. These partitions are divided among a number of database server processes
         	and can migrate between them.</para>
       </sect3>
       <sect3 id="clusterstcnfconf7why">
         <title>Why</title>
         <para>An Elastic cluster can be dynamically resized with new partitions or shards dynamically added to the
         	same or new hardware resources as the need to increase the size of the scale cluster or relocation of
         	partitions is required.</para>
       </sect3>
       <sect3 id="clusterstcnfconf7how">
         <title>How</title>
         <para>This documentation details the steps for the installation and configuration of a Virtuoso Elastic Cluster on Unix:</para>
         <orderedlist>
           <listitem><emphasis>Step 1</emphasis>: Perform Virtuoso 7 Unix installation;</listitem>
           <listitem><emphasis>Step 2</emphasis>: Determine Elastic Cluster size;</listitem>
           <listitem><emphasis>Step 3</emphasis>: Enable Elastic Cluster mode;</listitem>
           <listitem><emphasis>Step 4</emphasis>: Start Elastic Cluster;</listitem>
           <listitem><emphasis>Step 5</emphasis>: Splitting Cluster nodes across different machines.</listitem>
         </orderedlist>
       </sect3>
       <sect3 id="clusterstcnfconf7unix">
         <title>Virtuoso 7 Unix installation</title>
         <para><emphasis>Step 1</emphasis>: Perform Virtuoso 7 Unix installation</para>
<programlisting><![CDATA[
$ tar xvf virtuoso-universal-server-7.x.tar
x install.sh
x universal-server.taz
$ sh install.sh

- Extracting Virtuoso Universal Server v7.x

- Creating default environment settings

- Creating default database settings
Configuring: database
Creating directory $VIRTUOSO_HOME/database/backup
Installing new virtuoso.ini in $VIRTUOSO_HOME/database
Installing new php.ini in $VIRTUOSO_HOME/database
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t

- Registering ODBC drivers

- Registering .NET provider for Mono

- Installing VAD packages in database (this can take some time)

- Checking where license should be stored

- Starting OpenLink License Manager

- Checking for initial Virtuoso license

- Starting Virtuoso server instance

- Finalizing installation


This concludes the first part of the installation.


- Attempting to start browser

Please start a browser manually and open the following URL to finalize 
the installation process:

     http://cname:8890/install/


Installation completed
$
]]></programlisting>		
       </sect3>
       <sect3 id="clusterstcnfconf7clsize">
         <title>Determine Elastic Cluster size</title>
         <para><emphasis>Step 2</emphasis>: Determine Elastic Cluster size</para>
         <orderedlist>
           <listitem>Determine how many nodes you want to start the elastic cluster with: 2, 3, 4, 5, 6, 7, 8 etc. Note:
           	the number of the nodes must be &gt;= 2 </listitem>
  <listitem>Setup Virtuoso environment and stop default database: 
<programlisting><![CDATA[
$ . ./virtuoso-environment.sh
$ virtuoso-stop.sh
Shutting down Virtuoso instance in [database]
$
]]></programlisting>
  </listitem>
  <listitem>Optionally remove the default database such that is does not get started with the cluster: 
<programlisting><![CDATA[
rm  -rf database	
]]></programlisting>  	
  </listitem>
           <listitem>Full list of supported options for the script "virtuoso-mkcluster.sh":
<programlisting><![CDATA[
  -cluster-size       Number of nodes in cluster
  -cluster-node       Node number in a cluster
  -cluster-port       Base portnumer for cluster
  -cluster-ipc-port   Base portnumer for cluster IPC	
  -cluster_size       Size of the cluster
  -virtuoso_home      Virtuoso home path
]]></programlisting>  
  </listitem>
           <listitem>Run the virtuoso-mkcluster.sh script to create the cluster, note the default number of nodes is 4,
           	but this can be changed by setting the environment variable CLUSTER_SIZE to the required number of nodes to
           	be created before running the script:
<programlisting><![CDATA[
$ virtuoso-mkcluster.sh 
Configuring cluster node: 1/4

Creating directory $VIRTUOSO_HOME/cluster_01
Creating directory $VIRTUOSO_HOME/cluster_01/backup
Creating directory $VIRTUOSO_HOME/cluster_01/logs
Installing new virtuoso.ini in $VIRTUOSO_HOME/cluster_01
Installing new php.ini in $VIRTUOSO_HOME/cluster_01
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t
Configuring cluster node: 2/4

Creating directory $VIRTUOSO_HOME/cluster_02
Creating directory $VIRTUOSO_HOME/cluster_02/backup
Installing new virtuoso.ini in $VIRTUOSO_HOME/cluster_02
Removing unneeded sections from virtuoso.ini
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t
Configuring cluster node: 3/4

Creating directory $VIRTUOSO_HOME/cluster_03
Creating directory $VIRTUOSO_HOME/cluster_03/backup
Installing new virtuoso.ini in $VIRTUOSO_HOME/cluster_03
Removing unneeded sections from virtuoso.ini
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t
Configuring cluster node: 4/4

Creating directory $VIRTUOSO_HOME/cluster_04
Creating directory $VIRTUOSO_HOME/cluster_04/backup
Installing new virtuoso.ini in $VIRTUOSO_HOME/cluster_04
Removing unneeded sections from virtuoso.ini
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t
$
]]></programlisting>
  </listitem>
           <listitem>In each cluster_XX directory the following the <code>cluster.ini</code> files are created for cluster
           internal communication:
<programlisting><![CDATA[
$ more cluster_01/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host1
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = localhost:22201
Host2               = localhost:22202
Host3               = localhost:22203
Host4               = localhost:22204
MaxHosts            = 5
$ more cluster_02/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host2
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = localhost:22201
Host2               = localhost:22202
Host3               = localhost:22203
Host4               = localhost:22204
MaxHosts            = 5
$ more cluster_03/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host3
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = localhost:22201
Host2               = localhost:22202
Host3               = localhost:22203
Host4               = localhost:22204
MaxHosts            = 5
$ more cluster_04/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host4
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = localhost:22201
Host2               = localhost:22202
Host3               = localhost:22203
Host4               = localhost:22204
MaxHosts            = 5
$	
]]></programlisting>  	
  </listitem>
         </orderedlist>
       </sect3>
       <sect3 id="clusterstcnfconf7enmode">
         <title>Enable Elastic Cluster mode</title>
         <para><emphasis>Step 3</emphasis>: Enable Elastic Cluster mode</para>
         <orderedlist>
           <listitem>The <code>cluster.ini</code> files need to be reconfigured as detailed below for elastic cluster and
           file slicing/sharding to be enabled.</listitem>
           <listitem>A common file called <code>cluster.global.ini</code> can be created and placed in the home directory
           of the Virtuoso installation:
<programlisting><![CDATA[
[Cluster]
Threads             = 300
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 100
RDFLoadBytes        = 52428800
Host1               = localhost:22201
Host2               = localhost:22202
Host3               = localhost:22203
Host4               = localhost:22204
]]></programlisting>
           </listitem>
           <listitem>This file can then be sym-linked to each of the <code>cluster_XX</code> directories of the cluster,
           and its content will be merged with the <code>cluster.ini</code> in the respective directory of each node
           when starting the cluster.
<programlisting><![CDATA[
ln -s cluster.global.ini cluster_01/cluster.global.ini
ln -s cluster.global.ini cluster_02/cluster.global.ini
ln -s cluster.global.ini cluster_03/cluster.global.ini
ln -s cluster.global.ini cluster_04/cluster.global.ini
]]></programlisting>
           </listitem>
           <listitem>Edit each of the the <code>cluster.ini</code> files in the <code>cluster_XX</code> directories as
           follows to enable, elastic cluster mode:
<programlisting><![CDATA[
$ more cluster_01/cluster.ini
[Cluster]
Master              = Host1
ThisHost            = Host1

[ELASTIC]
Segment1 = 4G, database.db = q1
Slices = 6
MaxSlices = 2048

$ more cluster_02/cluster.ini

[Cluster]
Master              = Host1
ThisHost            = Host2

[ELASTIC]
Segment1 = 4G, database.db = q1
Slices = 6
MaxSlices = 2048

$ more cluster_03/cluster.ini

[Cluster]
Master              = Host1
ThisHost            = Host3

[ELASTIC]
Segment1 = 4G, database.db = q1
Slices = 6
MaxSlices = 2048

$ more cluster_04/cluster.ini

[Cluster]
Master              = Host1
ThisHost            = Host4

[ELASTIC]
Segment1 = 4G, database.db = q1
Slices = 6
MaxSlices = 2048
]]></programlisting>
           </listitem>
           <listitem>The <code>[ELASTIC]</code> section in the <code>cluster.ini</code> files above, enables the elastic
           cluster mode, where multiple <code>segments</code> and <code>stripes</code> as detailed in the standard
           Virtuoso documentation <link linkend="ini_Striping">database striping</link>.
           </listitem>The <code>Slices</code> parameter above should be set to the number of hardware threads on the
           CPUs running on. Thus in the example above where it is set to 6, this assumes all nodes are running on the
           same physical machine with 12 cores with hyper-threading enabled i.e. 24 threads, thus 6 per cluster node.
           <listitem>The <code>MaxSlices</code> parameter above sets the the maximum number of physical slices in the cluster.
           </listitem>
         </orderedlist>
       </sect3>
       <sect3 id="clusterstcnfconf7start">
         <title>Start Elastic Cluster</title>
         <para><emphasis>Step 4</emphasis>: Start Elastic Cluster</para>
         <orderedlist>
           <listitem>Start the Elastic cluster using the standard <code>virtuoso-start.sh</code> script run from the home
           directory of the Virtuoso installation,which automatically detects the number for nodes to be started:
<programlisting><![CDATA[

$ virtuoso-start.sh
Starting Virtuoso instance in [cluster_01]
Starting Virtuoso instance in [cluster_02]
Starting Virtuoso instance in [cluster_03]
Starting Virtuoso instance in [cluster_04]
$	
]]></programlisting>  	
  </listitem> 	
           <listitem>The default SQL port of the master node is 12201, as indicated in the virtuoso.ini file of the
           	cluster_01 directory, and can then be used for connecting to the newly created cluster and check its
           	status to ensure all nodes are online:
<programlisting><![CDATA[
$ isql 12201
Connected to OpenLink Virtuoso
Driver: 07.10.3211 OpenLink Virtuoso ODBC Driver
OpenLink Interactive SQL (Virtuoso), version 0.9849b.
Type HELP; for help and EXIT; to exit.
SQL> status('cluster_d');
REPORT
VARCHAR
_______________________________________________________________________________

Cluster: No samples, Please refresh

1 Rows. -- 22 msec.
SQL> status('cluster_d');
REPORT
VARCHAR
_______________________________________________________________________________

Cluster 4 nodes, 2 s. 5 m/s 0 KB/s  5% cpu 0%  read 0% clw threads 1r 0w 0i buffers 349144 2 d 0 w 0 pfs
cl 1: 2 m/s 0 KB/s  0% cpu 0%  read 0% clw threads 1r 0w 0i buffers 45391 2 d 0 w 0 pfs
cl 2: 0 m/s 0 KB/s  0% cpu 0%  read 0% clw threads 0r 0w 0i buffers 43367 0 d 0 w 0 pfs
cl 3: 0 m/s 0 KB/s  0% cpu 0%  read 0% clw threads 0r 0w 0i buffers 50129 0 d 0 w 0 pfs
cl 4: 0 m/s 0 KB/s  0% cpu 0%  read 0% clw threads 0r 0w 0i buffers 39383 0 d 0 w 0 pfs

5 Rows. -- 22 msec.
SQL>
SQL> cl_ping(1,500, 1000);

Done. -- 7 msec.
SQL> cl_ping(2,500, 1000);

Done. -- 52 msec.
SQL> cl_ping(3,500, 1000);

Done. -- 60 msec.
SQL> cl_ping(4,500, 1000);

Done. -- 51 msec.
SQL>
]]></programlisting>
           </listitem>
           <listitem>The <code>database.log</code> of the master node can be checked to verify the Elastic cluster mode
           has been enable on server startup, which will contain the entry <emphasis>PL LOG: Elastic cluster setup</emphasis>:
<programlisting><![CDATA[
$ more cluster_01/database.log

                Thu Oct 09 2014
05:11:49 { Loading plugin 1: Type `plain', file `wikiv' in `../hosting'
05:11:49   WikiV version 0.6 from OpenLink Software
05:11:49   Support functions for WikiV collaboration tool
05:11:49   SUCCESS plugin 1: loaded from ../hosting/wikiv.so }
05:11:49 { Loading plugin 2: Type `plain', file `mediawiki' in `../hosting'
05:11:49   MediaWiki version 0.1 from OpenLink Software
05:11:49   Support functions for MediaWiki collaboration tool
05:11:49   SUCCESS plugin 2: loaded from ../hosting/mediawiki.so }
05:11:49 { Loading plugin 3: Type `plain', file `creolewiki' in `../hosting'
05:11:49   CreoleWiki version 0.1 from OpenLink Software
05:11:49   Support functions for CreoleWiki collaboration tool
05:11:49   SUCCESS plugin 3: loaded from ../hosting/creolewiki.so }
05:11:49 { Loading plugin 4: Type `plain', file `im' in `../hosting'
05:11:49   IM version 0.61 from OpenLink Software
05:11:49   Support functions for Image Magick 6.8.1
05:11:49   SUCCESS plugin 4: loaded from ../hosting/im.so }
05:11:49 { Loading plugin 5: Type `plain', file `wbxml2' in `../hosting'
05:11:49   WBXML2 version 0.9 from OpenLink Software
05:11:49   Support functions for WBXML2 0.9.2 Library
05:11:49   SUCCESS plugin 5: loaded from ../hosting/wbxml2.so }
05:11:49 { Loading plugin 6: Type `attach', file `libphp5.so' in `../hosting'
05:11:49   SUCCESS plugin 6: loaded from ../hosting/libphp5.so }
05:11:49 { Loading plugin 7: Type `Hosting', file `hosting_php.so' in `../hosting'
05:11:49   Hosting version 3208 from OpenLink Software
05:11:49   PHP engine version 5.3.21
05:11:49   SUCCESS plugin 7: loaded from ../hosting/hosting_php.so }
05:11:49 { Loading plugin 8: Type `plain', file `qrcode' in `../hosting'
05:11:49   QRcode version 0.1 from OpenLink Software
05:11:49   Support functions for ISO/IEC 18004:2006, using QR Code encoder (C) 2006 Kentaro Fukuchi <fukichi@megaui.net>
05:11:49   SUCCESS plugin 8: loaded from ../hosting/qrcode.so }
05:11:49 OpenLink Virtuoso Universal Server
05:11:49 Version 07.10.3211-pthreads for Linux as of Oct  6 2014
05:11:49 uses parts of OpenSSL, PCRE, Html Tidy
05:11:51 SQL Optimizer enabled (max 1000 layouts)
05:11:52 Compiler unit is timed at 0.000403 msec
05:12:03 Checkpoint started
05:12:04 Roll forward started
05:12:04 Roll forward complete
05:12:07 PL LOG: Elastic cluster setup
05:12:08 Checkpoint started
05:12:09 Checkpoint finished, log reused
05:12:11 Checkpoint started
05:12:12 Checkpoint finished, log reused
05:12:12 PL LOG: new clustered database:Init of RDF
05:12:23 Checkpoint started
05:12:25 Checkpoint finished, log reused
05:12:50 PL LOG: Installing Virtuoso Conductor version 1.00.8727 (DAV)
05:12:51 Checkpoint started
05:12:53 Checkpoint finished, log reused
05:13:23 Checkpoint started
05:13:25 Checkpoint finished, log reused
05:13:26 Checkpoint started
05:13:26 Checkpoint finished, log reused
05:13:28 HTTP/WebDAV server online at 8890
05:13:28 Server online at 12201 (pid 15211)
05:13:29 ZeroConfig registration CLUSTER (MASALA)
]]></programlisting>
           </listitem>
           <listitem>The cluster node directories can also be checked, where the database slice/shard files i.e.
           	<code>database.db.X, database.db.Y, database.db.Z</code> can be seen:
<programlisting><![CDATA[
$ ls -ltr cluster_01
total 2322804
drwxr-xr-x. 2 virtuoso virtuoso      4096 Oct  9 04:26 backup
drwxr-xr-x. 2 virtuoso virtuoso      4096 Oct  9 04:26 logs
-rwxr-xr-x. 1 virtuoso virtuoso     70607 Oct  9 04:26 php.ini
lrwxrwxrwx. 1 virtuoso virtuoso        24 Oct  9 04:26 virtuoso -> ..//bin/virtuoso-iodbc-t
-rw-r--r--. 1 virtuoso virtuoso         0 Oct  9 04:26 database.pxa
-rwxr-xr-x. 1 virtuoso virtuoso      6594 Oct  9 04:33 virtuoso.ini
-rw-r--r--. 1 virtuoso virtuoso       137 Oct  9 05:03 cluster.ini
lrwxrwxrwx. 1 virtuoso virtuoso        21 Oct  9 05:04 cluster.global.ini -> ../cluster.global.ini
drwxr-xr-x. 2 virtuoso virtuoso    131072 Oct  9 05:37 dump
-rw-r--r--. 1 virtuoso virtuoso     32915 Oct  9 06:55 database.2pc
-rw-r--r--. 1 virtuoso virtuoso        25 Oct 10 02:24 database.map
-rw-r--r--. 1 virtuoso virtuoso  56623104 Oct 10 03:23 database-temp.db
-rw-r--r--. 1 virtuoso virtuoso 824180736 Oct 10 05:10 database.db.16
-rw-r--r--. 1 virtuoso virtuoso 723517440 Oct 10 05:10 database.db.8
-rw-r--r--. 1 virtuoso virtuoso 740294656 Oct 10 05:10 database.db.0
-rw-r--r--. 1 virtuoso virtuoso  33554432 Oct 10 05:10 database.db
-rw-r--r--. 1 virtuoso virtuoso         0 Oct 10 05:10 database.trx
-rw-r--r--. 1 virtuoso virtuoso     34234 Oct 10 05:10 database.log
$
]]></programlisting>
           </listitem>
         </orderedlist>
       </sect3>
       <sect3 id="clusterstcnfconf7split">
         <title>Splitting Cluster nodes across different machines</title>
         <para><emphasis>Step 5</emphasis>: Splitting Cluster nodes across different machines</para>
         <orderedlist>
           <listitem>To split the node across across physical machines for better scale out performance, scalability
           	and growth, simply perform a parallel Virtuoso installation on the additional physical machines and move
           	the cluster nodes required to the designated machine. Example, for the default 4 node cluster to be split
           	across two identical machines it would make sense to split 2 nodes across each machine, thus you would
           	move say the cluster_03 and cluster_04 directory nodes to the new machine (removing them from the original).
           	The <code>cluster.global.ini</code> file on each node would then need to be updated to set the HostXX
           	parameters to point to the new locations for nodes 03 and 04:
<programlisting><![CDATA[
$ more cluster.global.ini

[Cluster]
Threads             = 300
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 100
RDFLoadBytes        = 52428800
Host1               = hostname1:22201
Host2               = hostname1:22202
Host3               = hostname2:22203
Host4               = hostname2:22204

Machine 1 (hostname1)

$ more cluster_01/cluster.ini
[Cluster]
Master              = Host1
ThisHost            = Host1

[ELASTIC]
Segment1 = 4G, database.db = q1
Slices = 12
MaxSlices = 2048

$ more cluster_02/cluster.ini

[Cluster]
Master              = Host1
ThisHost            = Host2

[ELASTIC]
Segment1 = 4G, database.db = q1
Slices = 12
MaxSlices = 2048

Machine 2 (hostname2)

$ more cluster_03/cluster.ini

[Cluster]
Master              = Host1
ThisHost            = Host3

[ELASTIC]
Segment1 = 4G, database.db = q1
Slices = 12
MaxSlices = 2048

$ more cluster_04/cluster.ini

[Cluster]
Master              = Host1
ThisHost            = Host4

[ELASTIC]
Segment1 = 4G, database.db = q1
Slices = 12
MaxSlices = 2048
]]></programlisting>
           </listitem>
           <listitem>Note assuming the same number of CPU threads on each machine i.e. 24, then the <code>Slices</code>
           param can be doubled to 12 for each node in <code>cluster.ini</code>, as above.
           </listitem>
           <listitem>The cluster nodes can then be started on each machine, with 2 nodes being started on each in this
           	case to form the cluster:
<programlisting><![CDATA[
Machine 1 (hostname1)

$ virtuoso-start.sh
Starting Virtuoso instance in [cluster_01]
Starting Virtuoso instance in [cluster_02]
$

Machine 2 (hostname2)

$ virtuoso-start.sh
Starting Virtuoso instance in [cluster_03]
Starting Virtuoso instance in [cluster_04]
$
]]></programlisting>
           </listitem>
           <listitem>To stop the cluster use the standard <code>virtuoso-stop.sh</code> script on each machine, which
           automatically detects the number for nodes to be stopped:
<programlisting><![CDATA[
Machine 1 (hostname1)

$ virtuoso-stop.sh
Stopping Virtuoso instance in [cluster_01]
Stopping Virtuoso instance in [cluster_02]

Machine 2 (hostname2)

$ virtuoso-stop.sh
Stopping Virtuoso instance in [cluster_03]
Stopping Virtuoso instance in [cluster_04]
$
]]></programlisting>
           </listitem>
           <listitem>The <code>cl_exec('shutdown')</code> command can also be run from <code>isql</code> on any node
           of the cluster to shutdown all nodes at once:
<programlisting><![CDATA[
$ isql 12201
Connected to OpenLink Virtuoso
Driver: 07.10.3211 OpenLink Virtuoso ODBC Driver
OpenLink Interactive SQL (Virtuoso), version 0.9849b.
Type HELP; for help and EXIT; to exit.
SQL> cl_exec ('checkpoint');

Done. -- 2487 msec.
SQL> cl_exec ('shutdown');

*** Error 08S01: VD CL065: Lost connection to server
at line 2 of Top-Level:
cl_exec ('shutdown')
$
]]></programlisting>
           </listitem>
         </orderedlist>
       </sect3>
   </sect2>

   <sect2 id="clusterstcnfsetup">
<title>Virtuoso default Cluster Installation and Configuration</title>
<para>These sections apply to Virtuoso as of version 6.x and higher.</para>
<orderedlist>
	<listitem>Run the Virtuoso 6 Unix ( MacOsX) installer to perform a default installation:
<programlisting><![CDATA[
$ tar xvf virtuoso-universal-server-6.1.tar
x install.sh
x universal-server.taz
$ sh install.sh

- Extracting Virtuoso Universal Server v6.1

- Creating default environment settings

- Creating default database settings
Configuring: database
Creating directory $VIRTUOSO_HOME/database/backup
Installing new virtuoso.ini in $VIRTUOSO_HOME/database
Installing new php.ini in $VIRTUOSO_HOME/database
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t

- Registering ODBC drivers

- Registering .NET provider for Mono

- Installing VAD packages in database (this can take some time)

- Checking where license should be stored

- Starting OpenLink License Manager

- Checking for initial Virtuoso license

- Starting Virtuoso server instance

- Finalizing installation


This concludes the first part of the installation.


- Attempting to start browser

Please start a browser manually and open the following URL to finalize
the installation process:

     http://cname:8890/install/


Installation completed
$
]]></programlisting>
	</listitem>
  <listitem>Determine how many nodes you want to start the cluster with: 2, 3, 4, 5, 6, 7, 8 etc. <emphasis>Note</emphasis>:
  the number of the nodes should be &gt;= 2</listitem>
  <listitem>Setup Virtuoso environment and stop default database:
<programlisting><![CDATA[
$ . ./virtuoso-environment.sh
$ virtuoso-stop.sh
Shutting down Virtuoso instance in [database]
$
]]></programlisting>
  </listitem>
  <listitem>Optionally remove the default database such that is does not get started with the cluster:
<programlisting><![CDATA[
rm  -rf database
]]></programlisting>
  </listitem>
  <listitem>Full list of supported options for the script <emphasis>"virtuoso-mkcluster.sh"</emphasis>:
<programlisting><![CDATA[
  -cluster-size       Number of nodes in cluster
  -cluster-node       Node number in a cluster
  -cluster-port       Base portnumer for cluster
  -cluster-ipc-port   Base portnumer for cluster IPC
  -cluster_size       Size of the cluster
  -virtuoso_home      Virtuoso home path
]]></programlisting>
  </listitem>
  <listitem>Run the virtuoso-mkcluster.sh script to create the cluster, note the default number of
  	nodes is 4, but this can be changed by setting the environment variable CLUSTER_SIZE to the
  	required number of nodes to be created before running the script:
<programlisting><![CDATA[
$ virtuoso-mkcluster.sh
Configuring cluster node: 1/4

Creating directory $VIRTUOSO_HOME/cluster_01
Creating directory $VIRTUOSO_HOME/cluster_01/backup
Creating directory $VIRTUOSO_HOME/cluster_01/logs
Installing new virtuoso.ini in $VIRTUOSO_HOME/cluster_01
Installing new php.ini in $VIRTUOSO_HOME/cluster_01
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t
Configuring cluster node: 2/4

Creating directory $VIRTUOSO_HOME/cluster_02
Creating directory $VIRTUOSO_HOME/cluster_02/backup
Installing new virtuoso.ini in $VIRTUOSO_HOME/cluster_02
Removing unneeded sections from virtuoso.ini
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t
Configuring cluster node: 3/4

Creating directory $VIRTUOSO_HOME/cluster_03
Creating directory $VIRTUOSO_HOME/cluster_03/backup
Installing new virtuoso.ini in $VIRTUOSO_HOME/cluster_03
Removing unneeded sections from virtuoso.ini
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t
Configuring cluster node: 4/4

Creating directory $VIRTUOSO_HOME/cluster_04
Creating directory $VIRTUOSO_HOME/cluster_04/backup
Installing new virtuoso.ini in $VIRTUOSO_HOME/cluster_04
Removing unneeded sections from virtuoso.ini
Creating symlink to $VIRTUOSO_HOME/bin/virtuoso-iodbc-t
$
]]></programlisting>
  </listitem>
  <listitem>For each of the cluster_XX directories created edit the cluster.ini file and set the
  	HostXX parameter to the hostname:portno to be used by the cluster nodes for internal communication.
<programlisting><![CDATA[
$ more cluster_01/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host1
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = hostname:22201
Host2               = hostname:22202
Host3               = hostname:22203
Host4               = hostname:22204
MaxHosts            = 5
$ more cluster_02/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host2
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = hostname:22201
Host2               = hostname:22202
Host3               = hostname:22203
Host4               = hostname:22204
MaxHosts            = 5
$ more cluster_03/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host3
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = hostname:22201
Host2               = hostname:22202
Host3               = hostname:22203
Host4               = hostname:22204
MaxHosts            = 5
$ more cluster_04/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host4
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = hostname:22201
Host2               = hostname:22202
Host3               = hostname:22203
Host4               = hostname:22204
MaxHosts            = 5
$
]]></programlisting>
  </listitem>
  <listitem>Start the cluster using the standard virtuoso-start.sh script which automatically detects
  	the number for nodes to be started:
<programlisting><![CDATA[
$ virtuoso-start.sh
Starting Virtuoso instance in [cluster_01]
Starting Virtuoso instance in [cluster_02]
Starting Virtuoso instance in [cluster_03]
Starting Virtuoso instance in [cluster_04]
$
]]></programlisting>
  </listitem>
  <listitem>The default SQL port of the master node is 12201, as indicated in the virtuoso.ini file
  	of the cluster_01 directory, and can then be used for connecting to the newly created cluster
  	and check its status to ensure all nodes are online:
<programlisting><![CDATA[
$ isql 12201
Connected to OpenLink Virtuoso
Driver: 06.01.3127 OpenLink Virtuoso ODBC Driver
OpenLink Interactive SQL (Virtuoso), version 0.9849b.
Type HELP; for help and EXIT; to exit.
SQL> status ('cluster');
REPORT
VARCHAR
_______________________________________________________________________________

Cluster 4 nodes, 4 s. 1 m/s 0 KB/s  0% cpu 0%  read 0% clw threads 1r 0w 0i buffers 2981 0 d 0 w 0 pfs

1 Rows. -- 7 msec.
SQL> cl_ping(1,500, 1000);

Done. -- 7 msec.
SQL> cl_ping(2,500, 1000);

Done. -- 52 msec.
SQL> cl_ping(3,500, 1000);

Done. -- 60 msec.
SQL> cl_ping(4,500, 1000);

Done. -- 51 msec.
SQL>	
]]></programlisting>  	
  </listitem> 	
  <listitem>To split the node across across physical machines for better performance and scalability, 
  	simply perform a parallel Virtuoso installation on the additional physical machines and move the 
  	cluster nodes required to the designated machine. Example, for the default 4 node cluster to be 
  	split across two identical machines it would make sense to split 2 nodes across each machine, 
  	thus you would move say the cluster_03 and cluster_04 directory nodes to the new machine (removing 
  	them from the original). The cluster.ini file on each node would then need to be updated to set the 
  	HostXX parameters to point to the new locations for nodes 03 and 04: 
<programlisting><![CDATA[
Machine 1 (hostname1)

$ more cluster_01/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host1
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = hostname1:22201
Host2               = hostname1:22202
Host3               = hostname2:22203
Host4               = hostname2:22204
MaxHosts            = 5
$ more cluster_02/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host2
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = hostname1:22201
Host2               = hostname1:22202
Host3               = hostname2:22203
Host4               = hostname2:22204
MaxHosts            = 5
$

Machine 2 (hostname2)

$ more cluster_03/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host3
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = hostname1:22201
Host2               = hostname1:22202
Host3               = hostname2:22203
Host4               = hostname2:22204
MaxHosts            = 5
$ more cluster_04/cluster.ini
[Cluster]
Threads             = 20
Master              = Host1
ThisHost            = Host4
ReqBatchSize        = 10000
BatchesPerRPC       = 4
BatchBufferBytes    = 20000
LocalOnly           = 2
MaxKeepAlivesMissed = 1000
Host1               = hostname1:22201
Host2               = hostname1:22202
Host3               = hostname2:22203
Host4               = hostname2:22204
MaxHosts            = 5
$	
]]></programlisting>  	
  </listitem> 	
  <listitem>The nodes can then be started on each machine, with 2 nodes being started on each in this 
  	case to form the cluster:  
<programlisting><![CDATA[

Machine 1 (hostname1)

$ virtuoso-start.sh
Starting Virtuoso instance in [cluster_01]
Starting Virtuoso instance in [cluster_02]
$

Machine 2 (hostname2)

$ virtuoso-start.sh
Starting Virtuoso instance in [cluster_03]
Starting Virtuoso instance in [cluster_04]
$
]]></programlisting>  	
  </listitem> 	
  <listitem>To stop the cluster use the standard virtuoso-stop.sh script which automatically detects the number for nodes to be stopped:  
<programlisting><![CDATA[
$ virtuoso-stop.sh
Stopping Virtuoso instance in [cluster_01]
Stopping Virtuoso instance in [cluster_02]
Stopping Virtuoso instance in [cluster_03]
Stopping Virtuoso instance in [cluster_04]
$
]]></programlisting>  	
  </listitem> 	
</orderedlist>
</sect2>
<sect2 id="clusterstcnfbackuprestore">
<title>Backup and Restore</title>
    <para><emphasis>Backup</emphasis></para>
<para>There are 2 ways to backup Virtuoso Cluster DB:</para>
<orderedlist>
  <listitem>Backup every node using <link linkend="fn_backup_online"><function>back_online</function></link>
    <para><emphasis>For example, for every cluster in its backup folder execute:</emphasis></para>
<programlisting><![CDATA[
SQL> backup_online('dbp',10000000,0,vector('backup')); 

Done. -- 272 msec.
]]></programlisting>
</listitem>
  <listitem>Make backup of all nodes at once using <link linkend="fn_cl_exec">cl_exec()</link>. For example, execute:
<programlisting><![CDATA[
SQL> cl_exec ('backup_online (''dbp'', 10000000, 0,  vector (''backup''))');

Done. -- 573 msec.
]]></programlisting>
</listitem>
</orderedlist>
    <para><emphasis>Restore from Backup</emphasis></para>
<para>After backup is done for every node in its backup folder, in order to restore,
execute from the ..\bin folder the virtuoso-restore.sh:</para>
<programlisting><![CDATA[
# . ./virtuoso-restore.sh all dbp
]]></programlisting>
<para>where the second parameter is the restore prefix.</para>
    </sect2>
    <sect2 id="clusterstcnfconfig"><title>Cluster Configuration</title>
<orderedlist>
  <listitem>Set "FAST_START=1" in the viruoso-start.sh file and then run:
<programlisting><![CDATA[
viruoso-start.sh
]]></programlisting>
<para>or</para>
 </listitem>
  <listitem>Execute the following line:
<programlisting><![CDATA[
# /etc/init.d/virtuoso start
Starting OpenLink Virtuoso:                                [  OK  ]
]]></programlisting>
</listitem>
  <listitem>In order to check the nodes, connect to port 12201 using the ISQL tool:
<programlisting><![CDATA[
isql 12201
]]></programlisting>
</listitem>
  <listitem>To check the cluster status, execute the following command:
<programlisting><![CDATA[
SQL> status('cluster');
REPORT
VARCHAR
_______________________________________________________________________________

Cluster 4 nodes, 293 s. 0 m/s 0 KB/s  0% cpu 0%  read 0% clw threads 1r 0w 0i buffers 1781 0 d 0 w 0 pfs

1 Rows. -- 4 msec.
]]></programlisting>
</listitem>
</orderedlist>
    </sect2>

    <!-- ======================================== -->
     <sect2 id="clusterstcnfconfnodesconfig">
       <title>HTTP Service Configuration on Subordinate Nodes of a Virtuoso Cluster</title>
       <para>This section applies to Virtuoso as of version 6.x and higher.</para>
       <sect3 id="clusterstcnfconfnodesconfigwhat">
         <title>What</title>
         <para>This documentation details how to configure the Subordinate (also called Slave) Nodes of a Virtuoso Elastic Cluster
         	to service HTTP clients.</para>
       </sect3>
       <sect3 id="clusterstcnfconfnodesconfigwhy">
         <title>Why</title>
         <para>By default, only the Primary (also called Master) instance of a Virtuoso Elastic Cluster is configured to provide
         	HTTP services.</para>
         <para>The Subordinate (also called Slave) nodes of the cluster may also be configured to provide HTTP services,
         	enabling load balancing by spreading HTTP requests across the cluster's nodes.</para>
       </sect3>
       <sect3 id="clusterstcnfconfnodesconfighow">
         <title>How</title>
         <para>This documentation details the steps for the installation and configuration of a Virtuoso Elastic Cluster on Unix:</para>
         <orderedlist>
           <listitem><emphasis>Step 1</emphasis>: Set up each instance as a HTTP Server;</listitem>
           <listitem><emphasis>Step 2</emphasis>: Install and configure HTTP services on each instance;</listitem>
           <listitem><emphasis>Step 3</emphasis>: Configure load balancing.</listitem>
         </orderedlist>
       </sect3>
       <sect3 id="clusterstcnfconfnodesconfiginst">
         <title>Set up each instance as an HTTP Server</title>
         <para><emphasis>Step 1</emphasis>: Set up each instance as a HTTP Server</para>
         <para>Each node can be configured to provide HTTP services as follows:</para>
         <orderedlist>
           <listitem>Copy the <code>[HTTP Server]</code> section from the Primary instance's configuration file (by
           default, <code>virtuoso.ini</code>) to the configuration file of each Subordinate instance:
<programlisting><![CDATA[
[HTTPServer]
ServerPort                  = 8890
ServerRoot                  = ../vsp
DavRoot                     = DAV
EnabledDavVSP               = 0
HTTPProxyEnabled            = 0
TempASPXDir                 = 0
DefaultMailServer           = localhost:25
MaxClientConnections        = 5
MaxKeepAlives               = 10
KeepAliveTimeout            = 10
MaxCachedProxyConnections   = 10
ProxyConnectionCacheTimeout = 15
HTTPThreadSize              = 280000
HttpPrintWarningsInOutput   = 0
Charset                     = UTF-8
;HTTPLogFile                 = logs/http.log
MaintenancePage             = atomic.html
EnabledGzipContent          = 1
]]></programlisting>
           </listitem>
           <listitem>Edit the <code>ServerPort</code> parameter to make it unique on the machine hosting this instance;
           i.e., if a subordinate instance is running on same physical node as the primary instance, then the subordinate's
           HTTP port must to be changed (from 8890, for instance) to a unique port (e.g., 8891).</listitem>
           <listitem>Install the Virtuoso Conductor to enable HTTP Administration of the instance being configured. <i>Note:
           if the subordinate instance is not on the same machine as the primary instance, then the vad directory may also
           need to be copied from the primary instance to the subordinate instance.</i>:
<programlisting><![CDATA[
SQL> vad_install ('../vad/conductor_dav.vad', 0);
SQL_STATE  SQL_MESSAGE
VARCHAR  VARCHAR
_______________________________________________________________________________

00000    No errors detected
00000    Installation of "Virtuoso Conductor" is complete.
00000    Now making a final checkpoint.
00000    Final checkpoint is made.
00000    SUCCESS


6 Rows. -- 10263 msec.
SQL>
]]></programlisting>
           </listitem>
         </orderedlist>
       </sect3>
       <sect3 id="clusterstcnfconfnodesconfigservice">
         <title>Install and configure HTTP services on each instance</title>
         <para><emphasis>Step 2</emphasis>: Install and configure HTTP services on each instance</para>
         <para>Any HTTP services required on the subordinate instance will need to specifically installed or configured on
         	that physical node. For example, the Virtuoso default SPARQL endpoint (<code>/sparql</code>) may be configured by:</para>
         <orderedlist>
           <listitem>Log in into the Virtuoso Conductor http://hostname:port/conductor :
             <figure id="clst1" float="1">
               <title>Configure SPARQL Endpoint: log in</title>
               <graphic fileref="ui/cluster1.jpg"/>
             </figure>
           </listitem>
           <listitem>Go the the Web Application Server -&gt; Virtual Domains &amp; Directories tab:
             <figure id="clst2" float="1">
               <title>Configure SPARQL Endpoint: Virtual Domains and Directories</title>
               <graphic fileref="ui/cluster2.jpg"/>
             </figure>
           </listitem>
           <listitem>Select the New Directory Action for the Default Web Site HTTP host:
             <figure id="clst3" float="1">
               <title>Configure SPARQL Endpoint: new directory</title>
               <graphic fileref="ui/cluster3.jpg"/>
             </figure>
           </listitem>
           <listitem>Select the Type radio button and SPARQL access point item from the drop down list box:
             <figure id="clst4" float="1">
               <title>Configure SPARQL Endpoint: set type SPARQL</title>
               <graphic fileref="ui/cluster4.jpg"/>
             </figure>
           </listitem>
           <listitem>Click "Next".</listitem>
           <listitem>Enter /sparql as the Path param in the Virtual Directory Information section and click Save Changes:
             <figure id="clst5" float="1">
               <title>Configure SPARQL Endpoint: set /sparql virtual directory</title>
               <graphic fileref="ui/cluster5.jpg"/>
             </figure>
           </listitem>
           <listitem>The SPARQL endpoint will not be accessible on http://hostname:port/sparql the the newly configured slave nodes:
             <figure id="clst6" float="1">
               <title>Configure SPARQL Endpoint: SPARQL Endpoint</title>
               <graphic fileref="ui/cluster6.jpg"/>
             </figure>
           </listitem>
           <listitem>Further details on SPARQL endpoint configuration can be found in
           	<link linkend="rdfsupportedprotocolendpoint">Service Endpoint</link> documentation section.</listitem>
           <listitem>Typical Virtuoso server log output from a slave node when started, showing the HTTP server running on
           	port 8890, being:
<programlisting><![CDATA[
20:12:49 OpenLink Virtuoso Universal Server
20:12:49 Version 07.10.3209-pthreads for Linux as of Apr 26 2014
20:12:49 uses parts of OpenSSL, PCRE, Html Tidy
20:12:49 Registered to OpenLink Virtuoso (Internal Use)
20:12:49 Personal Edition license for 500 connections
20:12:49 Issued by OpenLink Software
20:12:49 This license will expire on Sun May 17 06:18:35 2015 GMT
20:12:49 Enabled Cluster Extension
20:12:49 Enabled Column Store Extension
20:12:57 Database version 3126
20:12:57 SQL Optimizer enabled (max 1000 layouts)
20:12:58 Compiler unit is timed at 0.000208 msec
20:12:58 Roll forward started
20:12:58 Roll forward complete
20:12:59 Checkpoint started
20:12:59 Checkpoint finished, log reused
20:12:59 HTTP/WebDAV server online at 8890
20:12:59 Server online at 12202 (pid 15969)
]]></programlisting>
           </listitem>
         </orderedlist>
       </sect3>
       <sect3 id="clusterstcnfconfnodesconfigload">
         <title>Configure load balancing</title>
         <para><emphasis>Step 3</emphasis>: Configure load balancing</para>
         <para>A reverse-proxy service (like Nginx or Apache) can then be configured such that requests are proxied across
         	as any or all nodes of the cluster, to provide the desired load balancing.</para>
       </sect3>
       <sect3 id="clusterstcnfconfnodesconfigaddinf">
         <title>Additional Information</title>
         <itemizedlist mark="bullet">
           <listitem>Only the Primary Node of an Elastic Cluster may be configured as a Publisher for Virtuoso Replication
           	Cluster purposes.</listitem>
           <listitem>The <ulink url="http://virtuoso.openlinksw.com/whitepapers/LOD2_D2.1.5_LOD_Cloud_Hosted_On_The_LOD2_Knowledge_Store_Cluster_500B_Triples.pdf">Virtuoso 500 billion triple Berlin SPARQL Benchmark (BSBM) dataset</ulink>
           runs were performed on a 24-node Elastic Cluster. Each node was configured to provide HTTP services and a SPARQL
           endpoint, and the query load was spread over the entire cluster.</listitem>
         </itemizedlist>
       </sect3>
     </sect2>

    <sect2 id="clusterstcnftrsh"><title>Troubleshooting Tips</title>
    <para>If an operation seems to hang, see the output of:</para>
<programlisting><![CDATA[
status ()	
]]></programlisting>    	
    <para>Check for the presence of the following conditions:</para>
<itemizedlist>
  <listitem>The cluster line shows 0% CPU, no message traffic and an unchanging number of buffers
wired, this is probably a bug. To reset, restart the cluster or the offending process if found.
Restart is done by executing:
<programlisting><![CDATA[
raw_exit (); 	
]]></programlisting>
<para>over an SQL connection to the process in question.</para>
  </listitem>
  <listitem>The cluster line shows many threads waiting compared to total threads. If CPU is 0 and
this does not change there could be a transaction that holds locks indefinitely. To clear, execute:
<programlisting><![CDATA[
txn_killall (1);	
]]></programlisting>
<para>Do this at a node that has local threads waiting. This is seen in the Lock Status
paragraph of status ('') when connected to the node in question.</para>
  </listitem>
  <listitem>The cluster line shows a changing number in the pfs field. The system is swapping
and slowed down.</listitem>
  <listitem>If the status () itself hangs, try another process of the cluster. See that there is
no temporary atomic activity like a long checkpoint. If the situation persists there is a bug.
The checkpoint can be seen by the presence of the <emphasis>checkpinmt_in_progress</emphasis> file 
in each server's working directory.</listitem>
  <listitem>To check the integrity of database files, do:
<programlisting><![CDATA[
cl_exec ('backup ''/dev/null''');
]]></programlisting>  	
<para>If this returns, the databases are OK. If one is found to be corrupt the corresponding server exits.</para>
</listitem>
</itemizedlist>
		</sect2>
   <tip><title>See Also:</title>
        <para><link linkend="clusteroperation">Setting up and operating Virtuoso on a cluster.</link></para>
        <para><link linkend="clusterprogramming">Virtuoso Cluster Programming</link></para>
        <para><link linkend="fault">Virtuoso Cluster Fault Tolerance.</link></para>
   </tip>
   
	</sect1>

</chapter>