Main -> Documentation -> Getting Started -> Installing and Configuring the Open SiteSearch Suite -> Installing Database Builder (Version 4.1.0/4.1.1)

Installing Database Builder (Version 4.1.0/4.1.1)

Table of Contents

Introduction
Requirements
Document Conventions
Installation Methods
Java Installation Procedure (UNIX and NT)
Perl Installation Procedure (UNIX)


Introduction

This document explains how to install version 4.1.0 or 4.1.1 of the SiteSearch Database Builder. The Open SiteSearch Database Builder installation process installs the database utility programs, the SiteSearch Database Operations Tool (SSDOT), the Record Builder application, and a local test database (localERIC) on your host system.

See Installing Database Builder (Version 4.0.x) for installing previous versions of the WebZ extension and Installing Database Builder (Version 4.1.2a) for the latest SiteSearch version.


Requirements

Before completing this installation, review the information in the Installing and Configuring the Open SiteSearch Suite and OCLC SiteSearch Suite System Requirements documents to ensure that you meet the system requirements and have all of the information that you need to install Database Builder successfully.

If you have not already installed the Web server/WebZ Extension and the WebZ software, OCLC recommends that you do so before you install the Database Builder software.


Document Conventions

  • <WebZ_root> refers to the location of your WebZ environment.
  • <WebServer_root> refers to the location of your Web server.
  • <version> refers to the SiteSearch version you are installing.
  • Items or commands you must type appear in single quotes, like this: "java DbBuilderInstaller_<version>". Type them without the quotes.

For Example

  • Your root directory (<WebZ_root>) might be /web/netscape/ss_prod. For NT administrators, your root directory might be j:\web\netscape\Ss_prod.
  • Your DbBuilderInstaller_<version>.class file might be DbBuilderInstaller _4_1_0.class
  • The Windows NT batch file might be DbBuilderInstaller_4_1_0.bat.

Record Builder and Web Servers

The Database Builder installation includes Record Builder, Record Builder is an end-user application built on WebZ technology that harnesses Database Builder's administrative utilities to allow the creation, modification, and maintenance of Newton searchable databases for local collections of such things as images, sound files, Web sites, and data. The Database Builder installation automatically installs Record Builder, but its use is optional.

The Database Builder installation asks you to specify the Web server port for Record Builder. If you are using the Apache Web server provided as part of the WebZ/Web Server Extension installation for UNIX systems, or a Netscape Web server, specify another port for Record Builder's Web server. If you are using the Microsoft Internet Information Server (IIS) as your Web server, it is not possible to run WebZ and Record Builder simultaneously on a single machine. Your options are to:

  • Use Netscape as your Web server, which will allow you to run WebZ and Record Builder simultaneously on the same machine
  • Use IIS as the Web server for a WebZ-only environment and Netscape as the Web server for a Record Builder-only environment or a WebZ/Record Builder environment
  • Use Netscape as the Web server for a WebZ-only environment and IIS as the Web server for a Record Builder-only environment
  • Use IIS as the Web server for a WebZ-only environment on one machine and IIS as the Web server for a Record Builder-only environment on another machine

Installation Methods

You can install the WebZ software using one of two methods, the Java Installation Procedure (UNIX and NT) (a graphical user interface), or the Perl Installation Procedure (UNIX).(a command line interface).


Java Installation Procedure (UNIX and NT)

Before you install the Database Builder software, configure your system environment variables. Read the instructions below, and make sure that you have the following installation files:

  • DbBuilderInstaller_<version>.bat (NT)
  • DbBuilderInstaller_<version>Class (UNIX and NT)

Time Required for Installation

Plan on about 20 minutes to install Database Builder using the Java installer. The specific time required depends on the speed of your processor and the system load at the time you perform the installation.

A Note to UNIX Administrators

The following instructions assume that you have configured your UNIX DISPLAY variable for your desktop display and started an X server session and terminal emulator window with a connection to the system hosting the Database Builder installation.

Directions

Follow the instructions below to install Database Builder using the Java installer.

Note:   Install Database Builder under the same user name (user account) that you used to install the WebZ Extension and WebZ. To conform to good system administration practices, we recommend that you do not use root as the user name in a UNIX environment.

 

1. Move to the <WebZ_root> directory.

2. Copy the files to your <WebZ_root> directory.

  • UNIX: Copy the DbBuilderInstaller_<version>Class file into your <WebZ_root> directory.
  • NT: Copy the DbBuilderInstaller_<version>Class file and the DbBuilderInstaller_<version>Bat file into your <WebZ_root> directory.

3. Start the installation process.

  • UNIX: Type "Java DbBuilderInstaller_<version>" and press Enter while you are in the <WebZ_root> directory.
  • NT: Double-click the DbBuilderInstaller_<version>Bat file.

4. The installation program extracts the compressed Java class file and begins the installation. The Welcome screen appears.

5. Click Next> on the Welcome screen to move to the System Configuration Information screen.

6. Enter the following information on the System Configuration Information screen:

  • Operating System - Select the appropriate operating system from the drop-down list.
  • Web Server for Record Builder - Select a Web server for Record Builder from the drop-down list. If you are using Microsoft IIS as your Web server, see Record Builder and Web Servers for your options.
  • JDK Location - the full path name of the Java Development Kit (JDK) on the host system. Example: /usr/java1.2
  • Perl Location - the full path name of the Perl interpreter.
    Example: /usr/local/bin perl.

Then click Next> to go to the Web Server Information screen.

7. Enter the following information on the Web Server Information screen:

  • Web Server Installation Directory - the full path name of the <WebServer_root> directory. Unless you are using the Microsoft IIS Server, this is normally <WebServer_root>.
  • Web Server Document Root Directory - the full path name of the directory that contains the Web server HTML files for the Record Builder interface. This should be a different directory than the Web Server Document Root Directory for the WebZ interface, although it should normally be a directory underneath <WebZ_root>/htdocs and is typically <WebZ_root>/htdocs/rbv0.
  •    
    Note:

    If you select the Apache Web server, the installer places the HTML and image files associated with the Apache server in this directory. For the Apache server, the document root directory should be <WebServer_root>/htdocs/rbv0.

  • Web Server CGI-BIN Directory - the full path name of the directory that contains any Common Gateway Interface (CGI) scripts used for the Web server and Record Builder operations. This is usually the same directory you defined as the Web Server CGI-BIN directory during the WebZ/Web Server Extension installation.
  • Web Server Host Name - the name of the host system for the Web server.
  • Host Name IP Address - the Internet Protocol (IP) address of the host system.
  • Web Server Port - the port number where you intend to run your Web server for the Record Builder application on the host system. This MUST be a different port than the one you specified during the Web Server/WebZ Extension installation.
  • Web Server Admin e-mail - the electronic mail (e-mail) address of the Open SiteSearch suite system administrator.
  • Process Username - the user name of the Open SiteSearch suite system administrator
  • Process Groupname - the name of the UNIX or NT group that has file permissions to the files and directories in the Web Server Installation directory.
  • Netscape Root Directory - the directory on the host system where the Netscape server is installed. This field only appears if you select Netscape as your Web server.

Then click Next> to proceed to the next screen, which has prompts for additional system information.

8. Enter the following information:

UNIX and NT Fields

  • WebZ Installation Root Directory - the full path name of the <WebZ_root> directory. This is normally the same directory you specified during the WebZ/Web Server Extension installation.
  • Database Builder Installation Root Directory - the full path name of the root directory for all Database Builder files. This should normally be <WebZ_root>.
  • Record Builder User Interface Version - User interface version for Record Builder. For SiteSearch 4.1.x, this must be the default, rbv0.
  • SSDOT Environment Name - a specific environment name for the Database Builder SSDOT program. This name appears in SSDOT menus to distinguish between multiple copies of SSDOT. This is useful if, for example, each institution in a consortium wishes to have a separate copy of SSDOT for the local databases it maintains. This allows you to determine which environment you are working in while running the SSDOT program.
  • SQLDriver Classname - the fully qualified class name of the Mini Structured Query Language (mSQL) driver. For UNIX, the default is com.imaginary.sql.msql.MsqlDriver, which is located in the msql-jdbc.jar file in the <WebZ_root>/msql/classes/lib directory. For Windows NT, the default is the default is sun.jdbc.odbc.JdbcOdbcDriver.

UNIX Fields

NT Fields

  • Host Name - the name of the host system that your SQL server runs on to provide user authentication to Record Builder.
    Example: admin.anywhereU.edu
  • JDBC URL - the Uniform Resource Locator (URL) and protocols that the Java Database Connectivity (JDBC) driver uses to locate your SQL server.

9. Click Next> to continue installing Database Builder.

10. You may receive a message asking whether you want to overwrite <WebZ_root>/COM/stevesoft/pat/AmpersandRule.class. Click Yes to All.

Note:  

You may receive this message after installer has already extracted some files (see step 11) instead of right after you click Next> in step 9.

11. While the installation proceeds, you can follow its progress by reading the messages displayed. You will see the following messages, in this order:

    Extracting files...

    Configuring initialization files. This may take several minutes, please wait...

    Moving DB BuilderExes. This may take several minutes, please wait...

    Cleaning up temporary files, please wait...

This part of the installation usually takes about 15 minutes.

12. When the installer completes its tasks, you see a screen that lists the number of files and directories extracted during the installation.

Note:

The number of extracted files and directories varies, and depends on your operating system.

13. Click Finish to end the installation.

14. Add the local version of the localERIC test database to your WebZ Out-of-the-Box Interface (OBI).

  • Open the databases.ini configuration file, located in the <WebZ_root>/ini directory, in a text editor.
  • Go to the [ZBaseDBs] section in the databases.ini file, and replace ERIC.ini with localERIC.ini, using the following syntax:
  •      dB* = dbs/localERIC.ini
  • Save and close the databases.ini file.

15. Check your Database Builder license for the basis of your licensing agreement. Is your Database Builder license based on the number of simultaneous users?

  • Yes. Verify the number of simultaneous users for which you are licensed. Go to step 16.
  • No. Go to step 18.
16. Open the OpServe_rb.ini configuration file (located in <WebZ_root>/ini/) with a text editor.

17. Specify the number of simultaneous Database Builder users in your license by editing the MaxSimultaneousUsers variable in the [RecordBuilderLicense] section of OpServe_rb.ini. Then save and close this file.

Note:

When the maximum number of Record Builder user sessions is already running, OpServe will not route the next user session to the appropriate JaSSI. The patron and/or staff member who tries to start a new session receives a message that the system is unavailable.

18. Navigate to your <WebZ_root> directory. Then delete the following files and directories:

  • install.idb
  • uninstall.class
  • /COM directory and its subdirectories
UNIX users:

To delete the /COM directory and its subdirectories with a single command, type the following at the command line: "rm -rf COM/".

19. Are you planning to use Record Builder?

  • Yes. Go to step 20.
  • No. Go to step 23. You are ready to test your new 4.1.x environment.

20. Set the startup and maximum sizes of the memory allocation pool for the JaSSIRB server. Open <NewWebZ_root>/scripts/ssmgr.hostname (where hostname is the name of the system where you installed your SiteSearch environment. Edit the jassi section of this file as follows:

  • For sites using the Java Development Kit (JDK) 1.1.x: Add -ms32m -mx32m, as shown in bold blue text.
     jassi) 
    
       if [ $# -eq 1 ] 
    
         then 
    
           java -ms32m -mx32m ORG.oclc.jassi.JaSSI $ROOTDIR/ini/JaSSIServer.ini &
    
         else 
    
           Java -ms32m -mx32m ORG.oclc.jassi.JaSSI $ROOTDIR/ini/$ININAME & 
    
      fi
  • For sites using JDK 1.2: Add -Xms32m -Xmx32m, as shown in bold blue text:
    jassi)
    
      if [ $# -eq 1 ] 
    
        then
    
          Java -Xms32m -Xmx32m ORG.oclc.jassi.JaSSI $ROOTDIR/ini/JaSSIServer.ini &
    
        else
    
          Java -Xms32m -Xmx32m ORG.oclc.jassi.JaSSI $ROOTDIR/ini/$ININAME & 
    
     fi

21. Edit the following variables in the [servername] section of <WebZ_root>/ini/JaSSIServer_rb.ini so that they read as follows:

LowUsedMemory  = 20000



MedUsedMemory  = 30000



HighUsedMemory = 40000
22. If you wish to use the sample databases provided with Record Builder, register these databases with SSDOT. Use each database's top-level directory (in <WebZ_root>/dbbuilder/dbs) as the database's name in SSDOT.
23. Test your installation now.


Perl Installation Procedure (UNIX)

Before you install the Database Builder software, read the instructions below. You should have the following installation files:

Time Required for Installation

Plan on about 10 to 15 minutes to install Database Builder using Perl scripts. The specific time required depends on the speed of your processor and the system load at the time you perform the installation.

Directions

Follow the instructions below to install Database Builder using Perl scripts.

Note:   Install Database Builder under the same user name (user account) that you used to install the WebZ Extension and WebZ. To conform to good UNIX system administration practices, we recommend that you do not use root as the user name.

1. Copy the Ss<version>.dbbuilder.tar.Z and DbBuilderInstaller_<version>.sh files into the <WebZ_root> directory.

2. Type "DbBuilderInstaller_<version>.sh" at the command prompt in the <WebZ_root> directory and press Enter to execute the installation scripts.

3. You see the following prompt:

    ********************************************************

    Installing the Open SiteSearch Database Builder - 4_1_1.

    ********************************************************
Do you want to continue? [y]

Press Enter or type "y".

4. You receive a series of prompts asking you for information needed to complete the installation. Accept the default value that appears by pressing Enter at the prompt (a bracketed value appears after most prompts; this is the default). If there is no default or the default value is incorrect, type the necessary information and press Enter. Definitions of each prompt, in the order in which they appear, follow.

  • Directory of Perl Interpreter - the full path name of the Perl interpreter on the host system.
  • DbBuilder Installation Directory - the full path name of the DbBuilder directory.
  • WebZ Installation Directory - the full path name of the <WebZ_root> directory.
  • Operating System - the operating system of your host environment. Enter the value for your operating system from those shown: "aix" (AiX), "osf1" (DIGITAL UNIX), "hpux" (HP-UX), "irix" (IRIX), or "sol" (Solaris).
  • SSDOT Environment Name - a specific environment name for the Database Builder SSDOT program. This name appears in SSDOT menus to distinguish between multiple copies of SSDOT. This is useful if, for example, each institution in a consortium wishes to have a separate copy of SSDOT for the local databases it maintains. This allows you to determine which environment you are working in while running the SSDOT program.
  • Web Server - Web server for Record Builder. Enter the value for your operating system from those shown. This is normally the same Web server you use for WebZ.
  • JDK Location - the full path name to the Java Development Kit (JDK) directory.
  • User Interface Version - User interface version for Record Builder. For SiteSearch 4.1.x, this must be the default, rbv0.
  • Web Server Document Root Directory - the full path name of the directory that contains the Web server HTML files for the Record Builder interface. This should be a different directory than the Web Server Document Root Directory for the WebZ interface, although it should normally be a directory underneath <WebZ_root>/htdocs and is typically <WebZ_root>/htdocs/rbv0.
  • Web Server CGI-BIN Directory - the full path name of the directory that contains any Common Gateway Interface (CGI) scripts used for the Web server and Record Builder operations. This is usually the same directory you defined as the Web Server CGI-BIN directory during the WebZ/Web Server Extension installation.
  • Host Name - the name of the host system for the Web server.
  • Host Name IP Address - the Internet Protocol (IP) address of the host system.
  • Web Server Port - the port number where you intend to run your Web server for the Record Builder application on the host system. This MUST be a different port than the one you specified during the Web Server/WebZ Extension installation.
  • miniSQL Port - the port number of the host system that the mSQL server runs on to provide user authentication to Record Builder. The port number must be the same port you assigned as the port number for the miniSQL port during the WebZ Installation and must be greater than 1024.
  • miniSQL Process Username - the user name of the mSQL system administrator.
  • Process Groupname - the name of the UNIX group that has file permissions to the files and directories in the <WebServer_root> directory.
  • miniSQL Server Admin Email - the electronic mail (e-mail) address of the mSQL system administrator.
  • SQLDriver Classname - The fully qualified class name of the Mini Structured Query Language (mSQL) driver. For UNIX, the default is com.imaginary.sql.msql.MsqlDriver, which is located in the msql-jdbc.jar file in the <WebZ_root>/msql/classes/lib directory.

5. A verification screen appears. Check this screen to ensure that the information you entered is correct. An example of the verification screen is shown below.


    Directory of Perl Interpreter: /usr/local/bin/perl

 DbBuilder Installation Directory: <WebZ_root>

Web Server Installation Directory: <WebServer_root>/httpd/apache_1.3.11
WebZ Installation Root: <WebZ_root>
JDK Location: usr/java1.2
Web Server CGI-BIN Directory: <WebServer_root>/cgi-bin
User Interface Version: rbv0 Server Document Root Directory: <WebServer_root>/htdocs/rbv0
Web Server Process Username: jsmith Host Name IP Address: 123.456.789.00 Web Server Port: 10085
Web Server Type: apache
Operating System: sol
miniSQL Port: 1026
miniSQL Process Username: jsmith
miniSQL Server Admin Email: jsmith@anywhereU.edu
SQLDriver Classname: com.imaginary.sql.msql.MsqlDriver
SSDOT Environment Name: <WebZ_root>/dbbuilder/ssdot Is this correct? [y]

6. Is everything on the verification screen correct?

  • Yes. Continue the installation by pressing Enter.
  • No. Type "n" and press Enter to cycle through the prompts again. Edit any value that you need to change. When the verification screen appears again, press Enter to continue with the installation.

7. While the installation proceeds, you see a number of messages. If you see the following messages, ignore them. They do not affect successful completion of the installation.


files: *lARCH.ini
orig str: 'SITESEARCHROOT' change str: '<WebZ_root>'
find: **lARCH.ini : No such file or directory
Successful completion of name change. files: *lARCH.ini.
orig str: '_FSEP_' change str: '/'
find: **lARCH.ini : No such file or directory.

Successful completion of name change.
files: *lERES.ini
orig str: 'SITESEARCHROOT' change str: <WebZ_root>'
find: **lERES.ini : No such file or directory.

Successful completion of name change.
files: *lERES.ini
orig.str: '_FSEP_' change str: '/'
find: **lERES.ini : No such file or directory
If no messages appear for a little while, do not be concerned. This part of the installation usually takes between 5 and 10 minutes.

8. When the installation script finishes, you see a message similar to the following:


-----------------------------------------
Database Builder install script Finished!
To use your localERIC database add it to
The SiteSearch databases.ini
----------------------------------------- creating ./config.status
Note:

Some UNIX platforms return an error message stating that the installer was unable to update the cache. However, this does not affect the installation. If you receive this message, ignore it.

9. Add the local version of the localERIC test database to your WebZ Out-of-the-Box Interface (OBI).

  • Open the databases.ini configuration file, located in the <WebZ_root>/ini directory, in a text editor.
  • Go to the [ZBaseDBs] section in the databases.ini file, and replace ERIC.ini with localERIC.ini, using the following syntax:
  •      dB* = dbs/localERIC.ini
  • Save and close the databases.ini file.

10. Check your Database Builder license for the basis of your licensing agreement. Is your Database Builder license based on the number of simultaneous users?

  • Yes. Verify the number of simultaneous users for which you are licensed. Go to step 11.
  • No. Go to step 13.
11. Open the OpServe_rb.ini configuration file (located in <WebZ_root>/ini/) with a text editor.

12. Specify the number of simultaneous Database Builder users in your license by editing the MaxSimultaneousUsers variable in the [RecordBuilderLicense] section of OpServe_rb.ini. Then save and close this file.

Note:

When the maximum number of Record Builder user sessions is already running, OpServe will not route the next user session to the appropriate JaSSI. The patron and/or staff member who tries to start a new session receives a message that the system is unavailable.

13. Are you planning to use Record Builder?

  • Yes. Go to step 14.
  • No. Go to step 17. You are ready to test your new 4.1.x <WebZ_root> environment.

14. Set the startup and maximum sizes of the memory allocation pool for the JaSSIRB server. Open <WebZ_root>/scripts/ssmgr.hostname (where hostname is the name of the system where you installed your SiteSearch environment. Edit the jassi section of this file as follows:

  • For sites using the Java Development Kit (JDK) 1.1.x: Add -ms32m -mx32m, as shown in bold blue text.
     jassi) 
    
       if [ $# -eq 1 ] 
    
         then 
    
           Java -ms32m -mx32m ORG.oclc.jassi.JaSSI $ROOTDIR/ini/JaSSIServer.ini &
    
         else 
    
           Java -ms32m -mx32m ORG.oclc.jassi.JaSSI $ROOTDIR/ini/$ININAME & 
    
      fi
  • For sites using JDK 1.2: Add -Xms32m -Xmx32m, as shown in bold blue text:
    jassi)
    
      if [ $# -eq 1 ] 
    
        then
    
          Java -Xms32m -Xmx32m ORG.oclc.jassi.JaSSI $ROOTDIR/ini/JaSSIServer.ini &
    
        else
    
          Java -Xms32m -Xmx32m ORG.oclc.jassi.JaSSI $ROOTDIR/ini/$ININAME & 
    
     fi

15. Edit the following variables in the [servername] section of <WebZ_root>/ini/JaSSIServer_rb.ini so that they read as follows:

LowUsedMemory  = 20000



MedUsedMemory  = 30000



HighUsedMemory = 40000
16. If you wish to use the sample databases provided with Record Builder, register these databases with SSDOT. Use each database's top-level directory (in <WebZ_root>/dbbuilder/dbs) as the database's name in SSDOT.

17. Test your installation now.


See Also

Installing and Configuring the Open SiteSearch Suite
Installing the WebZ Extension (Version 4.1.0/4.1.1)
Installing WebZ (Version 4.1.0/4.1.1)
databases.ini Configuration File
The SiteSearch Database Operations Tool (SSDOT)



[Main][Documentation][Support][Technical Reference][Community][Glossary][Search]

Last Modified: