# 2. Installation Guide

Chapter Contents | Prev | Next
Keyword Search:
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 "Download & Evaluation".

1. Select product "OpenLink Virtuoso: Personal Edition "

2. From "Product Category" choose "Universal Server"

3. From "Product" choose "Virtuoso Universal Server"

4. Select "Database Version"

5. From "server OS" select "Windows" and click "Next"

6. Select a release and click "Next"

7. You will be prompt to login in not already.

8. Click "Next"

9. Download the desired component. For example, click the HTTP link for "Multi-Threaded Universal Server (Commercial Edition) for OpenLink Virtuoso 4.x"

#### 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 database 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

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:

    C:\Program Files\OpenLink Software\Virtuoso 5.0\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:

- Virtuoso Drivers for ODBC
- Virtuoso Drivers for JDBC
- ISQL Utility
- ISQLO Utility
- Documentation
- Samples

#### 2.1.3.2. Server Components

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

- Virtuoso Virtual Database Servers for: ODBC based interfaces - the files "virtuoso-odbc-f" (for Virtuoso Lite) and "virtuoso-odbc-t" (For Virtuoso Enterprise Edition).
- Virtuoso HTTP Server.
- Virtuoso System Manager to configure the database through the HTTP interface.

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

Virtuoso Personal Edition Release 5.0 Installation on Windows

1. Double click on the Virtuoso Personal Edition installer (for example "ntvpz2zz.msi") to run the Windows installer.

   Figure: 2.1.4.1.1. Run the installer

2. The installer Welcome dialog is loaded:

   Figure: 2.1.4.1.1. The Welcome Screen

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

4. If a license file already exists the installer can place this in the correct location for use. Browse to the location of your installer file and the installer will use this for the Virtuoso Server. Alternatively the "Try & Buy" feature of the installer can be used to enable a trial or full license file to be obtained online.

   Figure: 2.1.4.1.1. The License File Location

5. Choose to obtain a Trial license for an evaluation or enter the shop site to purchase a full license.

   Figure: 2.1.4.1.1. The obtain Trial license screen

6. Click on the "Download License" button on the right to obtain the license file immediately. An e-mail will also be sent with details of the license and the location on the ODS account of the registered user where in can be obtained from at a later date. Once a license file is available on the machine use the "Browse" button to locate it and the "Set License" button to initialize the Virtuoso server with this license file.

   Figure: 2.1.4.1.1. The Download license screen

7. Choose the installation type that you want to install.

   Figure: 2.1.4.1.1. Setup Type

8. If the custom option was chosen, the installer prompts for the Destination folder of the installation.

   Figure: 2.1.4.1.1. Choose Destination Location

9. Select the Product Features to be installed.

   Figure: 2.1.4.1.1. Select Components

10. The Installation is now ready to proceed.

    Figure: 2.1.4.1.1. Proceed Installation

11. The Progress of the installation is indicated in the Status bar.

    Figure: 2.1.4.1.1. Status bar

12. The installation is now complete.

    Figure: 2.1.4.1.1. Complete Installation

13. The installer may prompt for the machine to be reboot if required.

    Figure: 2.1.4.1.1. Reboot prompt

14. Choose to change the "dba" and "dav" administrative user passwords from their default of "dba" and "dav" respectively to a value of your choice.

    Figure: 2.1.4.1.1. Reboot prompt

15. The Virtuoso Server Welcome page will now be displayed indicating the server is online. This Web based page can be used for general configuration and usage of the Virtuoso Server.

    Figure: 2.1.4.1.1. Reboot prompt

#### 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

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

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

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

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

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:

- Virtuoso Driver for ODBC
- Virtuoso Driver for JDBC
- Native Virtuoso Interactive SQL Query (ISQL)
- ODBC based Interactive SQL Query Utility (ISQLO)

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.

Previous Contents of Installation Guide | Chapter Contents | Next Virtuoso for Linux