www.openlinksw.com
docs.openlinksw.com

Book Home

Contents
Preface

Installation Guide

Virtuoso for Windows 95/98/NT/2000/XP
Existing Virtuoso 2.7 Users Before You Start Getting To Know Your Virtuoso Components Installation Steps Starting Your Virtuoso Server Post-Installation Sanity Check Creating and Deleting Virtuoso Services Configuring Virtuoso Client Components Default passwords
Virtuoso for Linux
Virtuoso for Unix
Virtuoso for Mac OS X

2.1. Virtuoso for Windows 95/98/NT/2000/XP

2.1.1. Existing Virtuoso 2.7 Users

You can migrate your existing Virtuoso servers to 3.0 using the migration utility. The Virtuoso database file structure has been considerably altered between versions. Please consult the Migration of Virtuoso from Version 2.7 to Version 3.0 section for more details.


2.1.2. Before You Start

To ensure a smooth installation, please review the following checklist before you start the setup program.

2.1.2.1. Have you downloaded the software?

If you have not already done so, please download your copy of OpenLink Virtuoso from the OpenLink web site. The URL is http://www.openlinksw.com. When you visit the site, select "Software availability and download".

The Windows file is a single executable for example ntvez30z.exe


2.1.2.2. Do you have the License file?

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.


2.1.2.3. Reinstalling Virtuoso?

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 "OpenLink Virtuoso DBMS Server [instance name]".

On Windows NT/2000/XP you can also shut them down with the following commands in the Virtuoso\bin directory:

virtuoso-odbc-t.exe +service stop
virtuoso-odbc-t.exe +instance myinstance +service stop
virtuoso-odbc-t.exe +instance anotherinstance +service stop
Note:

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.

You can list the services with their status using:

virtuoso +service list

2.1.2.4. Allocation of TCP/IP ports

The Default and Demo databases have the following port allocations:

Table: 2.1.2.4.1. Port Usage
Port Used by
1111 Default Virtuoso Server port
8889 Default Virtuoso Visual Server Administration Interface HTTP port
1112 Demo Virtuoso Server port
8890 Demo Virtuoso Visual Server Administration Interface HTTP port

During the installation you will be prompted for the HTTP port number on which the Virtuoso System manager will listen. If the port is already in use, you will encounter problems, and should choose another free port when you are prompted.

By default, the Virtuoso DBMS listens on port 1111 and the Demo database on 1112. These port numbers are 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:

C:\Program Files\OpenLink\Virtuoso\bin\virtuoso.ini

To check if a port is in use on NT, you can use the following command, and review the output:

netstat -an | more

2.1.2.5. Do you already have an ODBC Data Source Name (DSN) that works?

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.



2.1.3. Getting To Know Your Virtuoso Components

Virtuoso is made up of several components, these components fall into two distinct categories: Client Components and Server Components.

2.1.3.1. Client Components Package

These are the components typically used to communicate with a local or remote Virtuoso server, this includes:


2.1.3.2. Server Components

These are the components that service Virtuoso clients, these include:



2.1.4. Installation Steps

You can install Virtuoso in any one of the following configurations: Stand-Alone, 2-Tier Client-Server, or 3-Tier Client-Server.

2.1.4.1. Stand-Alone Configuration

In this scenario you have one machine making up your entire solution, which implies that your Applications, Virtuoso's client and server components, and the back end database engine(s) that you want to access via Virtuoso all reside on the same machine.

  1. Run the installer program, for example "ntvez30z.exe"

  2. The install engine will load.

    Figure: 2.1.4.1.1. The Prepare Screen
    The Prepare Screen
  3. This installer might have been compiled for an older version of the installer engine than the one on your system. This will be the case on an XP system without the Service Pack 1. Just confirm OK and continue with installation. It is not a serious problem.

    Figure: 2.1.4.1.1. Engine version Warning
    Engine version Warning
  4. Follow the installers on-screen instructions.

    Figure: 2.1.4.1.1. The Welcome Screen
    The Welcome Screen
  5. You read the full license agreement information and make sure that you agree with all the terms and conditions before proceeding with the installation.

    Figure: 2.1.4.1.1. License Agreement
    License Agreement
  6. Choose the installation type that you want to install. The "Client Only" option is for installing other client machines that will be used to access Virtuoso remotely, and so do not need the database installed.

    Figure: 2.1.4.1.1. Setup Type
    Setup Type
  7. You can transparently integrate Virtuoso with various hosting environments. Your system may show a subset of the available environments that are listed in the figure below.

    Figure: 2.1.4.1.1. Supported Hosting Environments
    Supported Hosting Environments
  8. Choose the destination directory for the installation. The installer will create the installation structure below this.

    Figure: 2.1.4.1.1. Choose Destination Location
    Choose Destination Location
  9. If you have already got files at this location, you will be warned.

    Figure: 2.1.4.1.1. Choose Destination Location
    Choose Destination Location
  10. Select the components that you want to install. Each selected item will have a tick in the tick-box. These are the only items that will be installed.

    Figure: 2.1.4.1.1. Select Components
    Select Components
  11. This warning may appear to inform you that the Virtuoso installer cannot find the Microsoft SMTP service. If you will not be using the SMTP features of Virtuoso this message can be ignored. If you will be using an alternative SMTP server possibly on another machine you can ignore this message. The installation will proceed in either case.

    Figure: 2.1.4.1.1. SMTP Service Warning
    SMTP Service Warning
  12. If you are installing to a directory that contained a previous installation of Virtuoso the installer may find that you already a demo database .db file. This prompt confirms whether you want it replaced.

    Figure: 2.1.4.1.1. Demo DB Overwrite Question
    Demo DB Overwrite Question
  13. The default database server requires a valid license file (virtuoso.lic) before it will successfully start. This file is usually delivered by email. If you are not in possession of a license file at this time then you can install it later manually.

    Figure: 2.1.4.1.1. Select License File
    Select License File
  14. Use this dialog to locate the license file that you wish to use. If you do not have a license file you will need to install it later, in which case you can cancel this dialog.

    Figure: 2.1.4.1.1. Select License File
    Select License File
  15. After the installation has completed you may want one of the installed Virtuoso servers to be started. Choose the appropriate action.

    Figure: 2.1.4.1.1. Select Startup Database
    Select Startup Database

    Virtuoso is installed as a Windows Service which can be started manually or automatically at boot time. These options let you choose which.

  16. Choose the server variant you wish to use for the default server. The list will only show supported environments as indicated earlier.

    Figure: 2.1.4.1.1. Select Default Server
    Select Default Server
  17. Choose the server variant you wish to use for the demo server. The list will only show supported environments as indicated earlier.

    Figure: 2.1.4.1.1. Select Demo Database Server
    Select Demo Database Server
  18. Figure: 2.1.4.1.1. Select Service Startup Type
    Select Service Startup Type
  19. Shortcuts to the program and documentation will be contained under a subdirectory of the Start Menu. Choose the name of the directory.

    Figure: 2.1.4.1.1. Select Program Folder
    Select Program Folder
  20. Press Next to begin copying files or press Back to change any of the settings of the installer.

    Figure: 2.1.4.1.1. Start Copying Files
    Start Copying Files
  21. Before any files can be copied the installer must make sure that there are now running Virtuoso services that will lock files that must be overwritten.

    Figure: 2.1.4.1.1. Preparing to Copy Files
    Preparing to Copy Files
  22. This will give an indication of the progress of the file copying process.

    Figure: 2.1.4.1.1. Copying Files Progress
    Copying Files Progress
  23. The Virtuoso includes a web server that can be used for administering the server remotely. You must choose a free TCP/IP port number for the web server listener to use. This is for the default Virtuoso server.

    Figure: 2.1.4.1.1. Database Server HTTP Port Select
    Database Server HTTP Port Select
  24. The Virtuoso Default server listens on a specific port for commands. You must choose a free TCP/IP port number for this.

    Figure: 2.1.4.1.1. Database Server Port Select
    Database Server Port Select
  25. Set the Administration password for the Default Virtuoso Server. Repeat the password to make sure you enter it correctly.

    Figure: 2.1.4.1.1. Default Server Administration Password
    Default Server Administration Password
  26. Set the DAV password for the Default Virtuoso Server. Repeat the password to make sure you enter it correctly.

    Figure: 2.1.4.1.1. Default Server DAV Password
    Default Server DAV Password
  27. If the Demo database was selected then this is configured in a similar way to the Default database. Set the Admin interface HTTP port.

    Figure: 2.1.4.1.1. Demo Database Server HTTP Port Select
    Demo Database Server HTTP Port Select
  28. Set the port for the Demo server.

    Figure: 2.1.4.1.1. Demo Database Server Port Select
    Demo Database Server Port Select
  29. Set the Administration password for the Demo Virtuoso Server. Repeat the password to make sure you enter it correctly.

    Figure: 2.1.4.1.1. Demo Server Administration Password
    Demo Server Administration Password
  30. Set the DAV password for the Demo Virtuoso Server. Repeat the password to make sure you enter it correctly.

    Figure: 2.1.4.1.1. Demo Server DAV Password
    Demo Server DAV Password
  31. As per your selection earlier, Virtuoso services will now be started.

    Figure: 2.1.4.1.1. Starting Demo Service
    Starting Demo Service
  32. The final confirmation of the completion of the installation. You may need to reboot the machine for the client drivers to be correctly installed.

    Figure: 2.1.4.1.1. Setup Complete
    Setup Complete
  33. If a server was started during the install, then the Administration page is shown in a web browser.

    Figure: 2.1.4.1.1. Administration Page
    Administration Page

2.1.4.2. 2-Tier Client-Server Configuration

In this scenario you have two logically distinct machine types making up your total solution, one machine hosts your Applications and Virtuoso client components, while the other hosts your Virtuoso and back-end Database Servers. This installation configuration format will allow Windows client machines to communicate with non Windows server machines running Virtuoso, it also allows Virtuoso clients on non Windows client machines to connect to Virtuoso servers on Windows server machines.

2.1.4.2.1. Client Components:
  1. Move the Virtuoso installation archive into a temporary installation folder on your Client machine

  2. Choose the Client install option. No further component selection will be required.

    Figure: 2.1.4.2.1.1. Setup Screens
    Setup Screens
  3. The installer will now extract and install your Virtuoso Client components


2.1.4.2.2. Server Components:
  1. Move the Virtuoso installation archive into a temporary installation folder on your Server machine.

  2. Choose the Server install option.

    Figure: 2.1.4.2.2.1. Setup Screens
    Setup Screens
  3. At the component selection, uncheck the "Virtuoso Drivers for ODBC" and "Virtuoso Drivers for JDBC" and the "Samples" check-boxes since you are only installing Virtuoso's Server components on this machine.

  4. The installer will now extract and install your Virtuoso Server components.



2.1.4.3. 3-Tier Client-Server Configuration

In this scenario you have three logically distinct machine types making up your total solution, the first machine hosts your Applications and Virtuoso client components (Client Machine), the second hosts your Virtuoso server, (Middle Tier Server Machine) and the third machine your back end Database Server (Database Server Machine). This installation configuration format will allow Windows client machines to communicate with non Windows middle-tier server machines running Virtuoso, as well as allowing Virtuoso clients on non Windows client machines to connect to Virtuoso servers on windows based middle-tier server machines.

2.1.4.3.1. Client Components:
  1. Move the Virtuoso installation archive into a temporary installation folder on your Client machine

  2. Choose the Client install option. No further component selection will be required.

    Figure: 2.1.4.3.1.1. Setup Screens
    Setup Screens
  3. The installer will now extract and install your Virtuoso Client components


2.1.4.3.2. Middle-Tier Server Components:

You need to install both the Virtuoso client and server components on this machine. This is due to the fact that in many cases this server will double as an Application Server, which entails having clients connecting to an application service that uses Virtuoso for data access.

  1. Move the Virtuoso installation archive into a temporary installation folder on your Server machine.

  2. Choose the Server install option.

    Figure: 2.1.4.3.2.1. Setup Screens
    Setup Screens
  3. At the component selection, uncheck the "Sample Application" check-box then the "Virtuoso Driver for ODBC" and "Virtuoso Drivers for JDBC" check-boxes since you are only installing Virtuoso's Server components on this machine.

  4. The installer will now extract and install your Virtuoso Server components.

You will not need to install anything on the remote database server since you will be connecting to remote database either via ODBC or Native Drivers installed on this Server.




2.1.5. Starting Your Virtuoso Server

Due to subtle differences between Windows 95/98 and Windows NT it is necessary to address the issue of starting and stopping your Virtuoso server for each one of these Windows variants separately.

2.1.5.1. Windows NT/2000/XP

You can start your Virtuoso server in one of two ways, automatically or manually, the default mode configured by your installer is Automatic.

2.1.5.1.1. Automatic Startup

Your Virtuoso servers (default and demonstration databases) are configured at installation time as "Automatic Startup" 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.


2.1.5.1.2. Manual Startup

You can manually start your Virtuoso server in one of two ways, either via the "services" control panel applet or from within a DOS shell. When doing this via the "Services" control panel Applet you need to simply open up your control panel and click on the "services" applet. This will present you with a screen similar to the one below:

Figure: 2.1.5.1.2.1. Services Applet
Services Applet

Click the "Start" or "Stop" button in order to start or stop a highlighted Virtuoso Server.

To start your Virtuoso servers manually using DOS command prompts, start a DOS shell and then enter the following command:

virtuoso-odbc-f +service start


2.1.5.2. Windows 95/98

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.

2.1.5.2.1. Automatic Startup

Your Virtuoso servers (default and demonstration databases) are configured at installation time as "Automatic Startup" 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.

If Virtuoso does not start automatically on Windows 95/98 after installation you will need to add the following line to the system's "autoexec.bat" file (assuming you have installed Virtuoso using the installers default installation folder):

C:\Program Files\OpenLink\Virtuoso\bin\virtuoso-odbc-f +service start

2.1.5.2.2. Manual Startup

You can start your Virtuoso servers manually by entering the following commands at the DOS command line prompt:

virtuoso-odbc-f +service start
virtuoso-odbc-f +instance demo +service start
Note:

If you encounter a "Program Not Found" error this is because your Virtuoso installation's "bin" sub-directory is not part of your PATH environment variable.




2.1.6. Post-Installation Sanity Check

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:

http://localhost:8889
http://localhost:8890
http://a_virtuoso_server.org:8890

See the following Quick Start chapter for further ways to verify the database.


2.1.7. Creating and Deleting Virtuoso Services

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 "Services" control panel applet. You do this by executing the following commands:

Adding new Virtuoso Server service: virtuoso-odbc-f +service create -I <your chosen service name>

Deleting an existing Virtuoso service: virtuoso-odbc-f +service delete -I <service that you are deleting>

Starting a new Virtuoso service manually: virtuoso-odbc-f +service start -I <service name>

Showing a list of existing Virtuoso services: virtuoso-odbc-f +service list

Note:

This functionality is only available on Windows NT/2000/XP.

Ensure that the services applet from the control panel is closed while issuing the above commands to prevent locking.


2.1.8. Configuring Virtuoso Client Components

The Virtuoso client components set consists of the following:

The sections that follow address the configuration and utilization of each one of these client components separately.

2.1.8.1. Virtuoso Driver for ODBC

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.

At installation time two ODBC data source names (DSN's) are created with default values by the Virtuoso installer, the first DSN named "Local Virtuoso" provides a link to a local default Virtuoso database server instance, while the other named "Local Virtuoso Demo" provides a link to a local Virtuoso server for the Virtuoso demonstration database.

See Also:

the Data Access Interfaces chapter for more detailed information regarding the Virtuoso ODBC Driver setup


2.1.8.2. Virtuoso Drivers for JDBC

The Virtuoso Drivers for JDBC are available in "jar" 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 "jar" 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.

See Also:

The JDBC Driver section in the Access Interfaces chapter.


2.1.8.3. Native Virtuoso Interactive SQL Query (ISQL)

To assist you with the use of Virtuoso an interactive SQL interpreter utility called "ISQL" 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.

The command line format for executing this utility is:

isql [<hostname>][:<port#>]

The steps that follow guide you through the process of using ISQL to verify your Virtuoso installation:

  1. Open up a DOS shell

  2. Move into the "bin" sub-directory of your Virtuoso installation

  3. Type the following command: isql

    This will connect you to the default Virtuoso server at port "1111", if you want to connect to your demonstration Virtuoso database (which listens at port 1112 by default) then enter: isql 1112

  4. At the ISQL command line prompt type in the following command:

    tables ;

    This will produce a list of tables in the current Virtuoso database, you can also enter other SQL statements e.g.:

    select * from Customers

    This will produce a listing of records in the "Customers" table.

  5. 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.


2.1.8.4. ODBC based Interactive SQL Query Utility (ISQLO)

In addition to a Native ISQL utility, your Virtuoso installation includes an ODBC based version of "ISQL" called "ISQLO", this enable you to connect to ODBC DSN's rather than Virtuoso only. To use this program perform the following steps:

  1. Open up a DOS shell

  2. Move into the "bin" sub-directory of your Virtuoso installation

  3. Type the following command :

    isqlo <enter a valid ODBC Data Source Name>
    Note:

    If your DSN contains spaces you will need to enclose it within double quotes when passing it as a parameter to ISQLO

  4. Enter any valid SQL at the ISQLO command line prompt.

  5. You can also use this utility from within the Virtuoso Conductor



2.1.9. Default passwords

See the following Quick Start chapter for very important information about changing the default passwords.