Main -> Documentation -> Product Updates -> Upgrading from Open SiteSearch 4.1.1 to SiteSearch 4.1.2a

Upgrading from OCLC SiteSearch 4.1.1 to SiteSearch 4.1.2a

 

Table of Contents

Introduction
Requirements
Document Conventions
Determining Your Upgrade Path
Applying 4.1.2/4.1.2a Bug Fixes to an Existing SiteSearch Environment
Upgrading from Version 4.1.1 to a Complete 4.1.2a Environment
     – WebZ Upgrade Procedure
     – Database Builder Upgrade Procedure
Appendices


Introduction

This document provides instructions for integrating customizations from an existing SiteSearch 4.1.1 environment into the Open SiteSearch 4.1.2a software on UNIX or Windows NT systems.

SiteSearch 4.1.2a includes new features introduced in both SiteSearch 4.1.2 and is the most current software release.

WARNING: If you have customized your SiteSearch environment, you must follow one of the upgrade procedures described in this document. DO NOT install the 4.1.2a software package into your existing environment. You will lose all of your changes by installing version 4.1.2a on top of an existing environment.


Requirements

Before completing the instructions in this document, you must:


Document Conventions

  • <WebZ_root> refers to your existing Open SiteSearch 4.1.1 environment.
  • <WebZWork_root> refers to a directory with a copy of your existing 4.1.1 environment.
  • <NewWebZ_root> refers to the directory where you install the Open SiteSearch 4.1.2a software. You integrate changes from version <WebZWork_root> into <NewWebZ_root>, while allowing patrons to access the <WebZ_root> environment during the upgrade.
  • <fullpath to JDK> is the full path to your Java Development Kit (JDK) installation.
  • When a procedure step refers to editing a file, use the text editor of your choice to edit the file. Then save and close the file.
  • In path names, forward slashes ("/") separate directories. For Windows NT, change the forward slashes to backslashes ("\").

Determining Your Upgrade Path

Ask yourself the following questions to determine how to proceed with upgrading your existing SiteSearch environment. While it is quicker to install only the bug fixes, you lose the opportunity to take advantage of the new features available in version 4.1.2a by installing only the bug fixes.

1. Are you using OCLC Database Builder's Record Builder application?

  • Yes. Go to Question 3.
  • No. Go to Question 2.

2. Do you want to install bug fixes only or bug fixes and enhancements? OCLC recommends that you upgrade to a complete 4.1.2a environment.

3. Have you customized SiteSearch in ANY way?



Applying 4.1.2/4.1.2a Bug Fixes to an Existing SiteSearch Environment (for Sites Not Using Record Builder)

For WebZ-only environments, the following procedure describes how to integrate 4.1.2/4.1.2a bug fixes into an existing 4.1.1 environment with the SS4_1_2a.jar file. This procedure will not work for sites that use Database Builder's Record Builder application.

By completing the steps below, you receive only the bug fixes made to the SiteSearch software in the 4.1.2/4.1.2a release. To integrate the complete 4.1.2a software package with an 4.1.1 existing environment, see Upgrading from Version 4.1.1 to a Complete 4.1.2a Environment.

1. Have you downloaded any patches or bug fixes with .class files from the SiteSearch FTP site for Java classes for which we do not provide the .java source files?

  • Yes. Delete these .class files before proceeding to step 2.
  • No. Go directly to step 2.

2. Back up your existing environment in a separate directory.

  • Stop the Web server, the WebZ system, and, if you are providing user authorization through the WebZ interface, the SQL server.
  • Copy the <WebZ_root> environment into a backup directory. This backup directory is a safeguard only; you do not use it in this procedure.

3. Create a temporary directory (<TempDir_root>) and install the SiteSearch 4.1.2a WebZ component in this directory.

4. Copy the SS4_1_2a.jar file and the pears.jar file from the <TempDir_root>/classes/lib directory into the <WebZ_root>/classes/lib directory. There should now be two SS*.jar files in the <WebZ_root>/classes/lib directory, SS4_1_1.jar and SS4_1_2a.jar.

5. Edit your CLASSPATH environment variable to read the SS4_1_2a.jar and pears.jar files.

An example of the required CLASSPATH statements follows.

.:<fullpath to JDK>/lib/classes.zip:<WebZ_root>/classes/: \
<WebZ_root>/classes/lib/pears.jar: \
<WebZ_root>/classes/lib/SS4_1_2a.jar: \
<WebZ_root>/classes/lib/mail.jar: \
<WebZ_root>/classes/lib/activation.jar

Note:

(1) In the example, backslash ("\") characters are included for readability only. Do NOT add them to the CLASSPATH variable.

(2) Edit the CLASSPATH variable so that its entries appear exactly in the order shown in the examples.

(3) Windows NT administrators need to set the CLASSPATH manually for this upgrade, even though you do not need to do this in a first-time installation. Use the syntax below except for substituting backslashes ("\") for forward slashes ("/") to separate file names.

(4) For more information about setting the CLASSPATH variable, see Configuring the CLASSPATH Variable for UNIX or Configuring the CLASSPATH Variable for NT in Installing and Configuring the Open SiteSearch Suite.

UNIX Administrators: After you edit your CLASSPATH variable, log out of your UNIX session and log back in to activate the new settings.

6. Edit the ssmgr.hostname file (in the <WebZ_root>/scripts directory), where hostname is the name of the host system where your existing Open SiteSearch environment is installed, in a text editor. You must change the following item, which is above "DO NOT edit below this line" statement, to reflect the 4.1.2a version of the software.

# What version of SiteSearch is installed
SSVERSION=4_1_2a

7. Edit the ssadmin file (in the <WebZ_root>/scripts directory) in a text editor. Change the item shown in to reflect the 4.1.2a version of the software:

SSVERSION=4_1_2a

8. Use a text editor to edit the SSVERSION line (as you did for ssadmin in step 7) in the following files in <WebZ_root>/scripts:

  • ber2marc
  • ber2txt
  • bounce
  • ssadminbatch
  • zclient

9. Test the <WebZ_root> environment. Start the Web server, SQL server (if necessary), and the WebZ system. Start a new WebZ user session in a Web browser, and perform several searches. Make sure to check all of the WebZ functionality through the interface, such as:

Debug any problems that have been introduced with this integration using the Troubleshooting the WebZ System document.



Upgrading from Version 4.1.1 to a Complete 4.1.2a Environment

The following procedures describe how to integrate your customizations into a SiteSearch 4.1.2a environment. Follow the instructions below carefully to preserve the changes you have made to the SiteSearch software. Print these instructions and use them as a checklist for upgrading your environment.

See Description of the Open SiteSearch 4.1.2 Release and Description of the Open SiteSearch 4.1.2a Patch Release for a description of the software upgrades included in version 4.1.2a.

The upgrade involves:

  • Making a copy of your existing SiteSearch 4.1.1 environment, in a new directory, <WebZWork_root>.
  • Installing all 4.1.2a components you have licensed in another new directory, <NewWebZ_root>.
  • Apply changes you made to your 4.1.1 environment by comparing the files you customized to those in <NewWebZ_root> and updating files in <NewWebZ_root> accordingly.
  • Verifying that the SiteSearch 4.1.2a environment in <NewWebZ_root> operates properly.
  • Making <NewWebZ_root> your new production environment.

There are two procedures in this section, one for WebZ and one for Database Builder. If your environment includes Database Builder, you must complete the WebZ upgrade before you begin the Database Builder upgrade.

Important: Perform and test these instructions in a test environment before implementing your customized 4.1.2a software in a production environment.

WebZ Upgrade Procedure

Note:  

This procedure notes several places where you can use SiteSearch's ability to version an interface to place your customized configuration files and HTML files in separate directories in your SiteSearch 4.1.2a environment. Although this is not required, we suggest that you consider this practice beginning with SiteSearch 4.1.2a.

If you choose to do this, a useful convention is to give the subdirectories for customized files the same name. For example, if you choose our_config as the directory name for customized files, you would create directories named <NewWebZ_root>/ini/interface/our_config, <NewWebZ_root>/ini/format/our_config, and <NewWebZ_root>/htdocs/our_config.

If you choose not to do this, where procedure steps refer to copying or editing files in an our_config directory in <NewWebZ_root>, such as <NewWebZ_root>/ini/format/our_config, substitute /obiv1 for our_config.

Creating a SiteSearch 4.1.2a Environment

1. Make a copy of your existing 4.1.1 environment in a new directory (<WebZWork_root>).

  • Stop the Web server, the WebZ system, and, if you are providing user authorization through the WebZ interface, the SQL server in your <WebZ_root> environment.
  • Copy the <WebZ_root> environment into the <WebZWork_root> directory.
  • Restart the Web server, SQL server, and WebZ system in <WebZ_root>.

You will work in the <NewWebZ_root> directory during this procedure, while still providing patron access to the <WebZ_root> environment until you complete the upgrade.

2. Create a new directory (<NewWebZ_root>) for installing the 4.1.2a software.

Note:  

<NewWebZ_root> becomes your new <WebZ_root> environment after you complete these upgrade instructions.

3. Install all the version 4.1.2a SiteSearch components you have licensed in <NewWebZ_root>. See Installing and Configuring the Open SiteSearch Suite for an overview of the installation process and the links in that document for installation instructions for each SiteSearch component.

Note:  

During the installation, use different port numbers for the Web server for WebZ, the SQL server, and the Record Builder Web server (if applicable) than those for your production environment.

4. Test the 4.1.2a installation and examine the new features included in version 4.1.2a. If you are using the FirstSearch databases demonstrated in the OBI, version 1, note the record formats provided in version 4.1.2a.

Making Customizations to Files in <NewWebZ_root>/ini

5. Update .ini files in <NewWebZ_root>/ini with any customizations to these files you made in your 4.1.1 environment:

  • Use the UNIX diff utility to identify the differences between the .ini files in <WebZWork_root>/ini and <NewWebZ_root>/ini. See Appendix A for a list of the files in <WebZWork_root>/ini with changes in version 4.1.2a.
  • (Optional) Make a copy of the files that you need to update in <NewWebZ_root>/ini in a separate directory, such as <NewWebZ_root>/ini/412ship.
  • Edit each .ini file in <NewWebZ_root>/ini, as necessary, to incorporate any customizations you made to these files.
Notes:  

In <NewWebZ_root>/ini/JaSSIServer.ini:

(1) Do not remove or modify these lines in the [ServerMngr] section:

  • server3 = OclcISOILL
  • server4 = EmailILL
  • server5 = MimeEmailILL
and the new [OclcISOILL], [EmailILL], and [MimeEmailILL] sections.

(2) If your customized HTML files and interface style, interface display and topic configuration files currently reside in directories other than the defaults shown (or you will be separating them from the /obiv1 files for the first time in <NewWebZ_root>), change the path in the appropriate variables. These are most like to be the DocumentRoot, TimeoutPage, and FailurePage variables in the [JaSSI] section, and the [Topics], [InterfaceStyles], and [InterfaceDisplayGadgets] sections.

(3) Add any class packages you have created for customized Java classes to the [PackageOrder] section.

(4) Edit the [servername] section to reflect the threshold values you used in your 4.1.1 production environment.

Updating and Copying Interface Style, Interface Display, and Topic Configuration Files

6. Incorporate your customizations to interface style, interface display, and topic configuration files into the 4.1.2a environment in <NewWebZ_root>:

  • Use the UNIX diff utility or another utility that can identify the differences between two files to compare your customized versions of the files in <WebZWork_root>/ini/interface/our_config (where our_config is the directory that contains your customized files) to the 4.1.2a versions of these files in <NewWebZ_root>/ini/interface/obiv1. See Appendix A for a list of the changed files and Appendix B for the new or modified sections in the 4.1.2a versions of these files.
  • Create a separate directory for your customized interface style configuration files under <NewWebZ_root>/ini/interface, such as our_config.
  • Copy the files from <WebZWork_root>/ini/interface/our_config or /obiv1 to <NewWebZ_root>/ini/interface/our_config.
  • Edit the appropriate file(s) in <NewWebZ_root>/ini/interface/our_config to add your customizations to these files.

Updating and Copying Server Configuration Files (except for ILL-related files)

7. (Optional, but recommended) Move the vendor-specific server configuration files delivered with SiteSearch 4.1.2a to a separate directory under <NewWebZ_root>/ini/servers, such as /412aship.

8. Copy your database-specific versions of server configuration files from <WebZWork_root>/ini/servers to <NewWebZ_root>/ini/servers.

Note:  

If you have FirstSearch databases, you may wish to make a copy of the 4.1.2a FirstSearch.ini file with a different name. This allows you to retain the information provided in this file about access to the FirstSearch 5 test server.

9. Compare other server configuration files in <WebZWork_root>/ini/servers to their counterparts in <NewWebZ_root>/ini/servers. See Appendix A for a list of server configuration files with changes in SiteSearch 4.1.2a. Edit files in <NewWebZ_root>/ini/servers as needed.

Updating and Copying Interlibrary Loan Files

10. Are you using WebZ's Interlibrary Loan (ILL) capabilities in your 4.1.1 production environment?

  • Yes. SiteSearch 4.1.2a uses separate ILL server configuration files for each ILL service type. The generic server configuration files for OCLC ILL Direct Request and e-mail delivery of ILL requests are <NewWebZ_root>/ini/servers/OclcISOILL.ini and <NewWebZ_root>/ini/servers/EmailILL.ini, respectively. Therefore, you must copy the relevant information from <WebZWork_root>/ini/servers/IllService.ini to these new files. See Appendix C for the information to copy to each file.
  • No. Go to step 12.

11. Are you using WebZ with the OCLC ILL Direct Request Service?

  • Yes. If you are using location configuration files, copy all the files from <WebZWork_root>/ini/loc to <NewWebZ_root>/ini/loc. Then go to step 12.

  • No. Go to step 12.

Updating and Copying Formatting Configuration Files

12. Appendix A contains a list of formatting configuration files modified in SiteSearch 4.1.2a and the new or modified information in each of these files. Have you customized any of these files in your 4.1.1 environment?

  • Yes.
    • Use the UNIX diff utility or another utility that can identify the differences between two files to compare the customized versions of your formatting configuration files in <WebZWork_root>/ini/interface/our_config or /obiv1, (where our_config is the directory that contains your customized files) to the new 4.1.2a versions of these files in <NewWebZ_root>/ini/format/obiv1.
    • Edit the appropriate file(s) in <WebZWork_root>/ini/interface/our_config or /obiv1 to add your customizations to these files.
    • Create a new directory for your customized formatting configuration files under <NewWebZ_root>/ini/format, such as /our_config.
    • Copy all files in <WebZWork_root>/ini/interface/our_config or /obiv1 to <NewWebZ_root>/ini/format/our_config.
    • Copy the formatting new configuration files listed in Appendix A to <NewWebZ_root>/ini/format/our_config.
  • No.
    • Create a new directory for formatting configuration files under <NewWebZ_root>/ini/format, such as /our_config. This allows you to subsequently modify these files without modifying the original versions in the /obiv1 directory.
    • Copy all the files from <NewWebZ_root>/ini/format/obiv1 to <NewWebZ_root>/ini/format/our_config.
    • If your 4.1.1 environment in <WebZWork_root>/ini/interface/our_config or /obiv1 contains any formatting configuration files not delivered with the 4.1.1 OBI, version 1, copy these files to <NewWebZ_root>/ini/format/our_config.

13. If any formatting configuration files in <NewWebZ_root>/ini/format/our_config/contain #include statements with a path reference like

#include "format/obiv1/format_config_file.ini"

edit the path so that it refers to the <NewWebZ_root>/format/our_config directory.

Updating and Copying Database Configuration Files

14. For each database configured for ILL, edit the IllService variable in the [database] section of its database configuration file in <WebZWork_root>/ini/dbs, as follows:

  • If IllService = ISOILL, change it to IllService = OclcISOILL.
  • If IllService = EMAIL, change it to IllService = EmailILL.
15. For all database configuration files in <WebZWork_root>/ini/dbs, modify the paths to formatting configuration files in the [formats] section so they refer to the /our_config directory under <NewWebZ_root>/ini/format.

16. For each library catalog database, add these lines to the [formats] section of its database configuration file in <WebZWork_root>/ini/dbs:

illKey           = format/our_config/ILLDoubleCheck.ini
dblcheckholdings = format/our_config/MarcCatalogFormats.ini
(except for DRA Classic)

dblcheckholdings = format/our_config/DRAILLFormat.ini (for DRA Classic only)
localholdingshdr = format/our_config/MarcCatalogFormats.ini

17. For each article index database, add this line to the [formats] section of its database configuration file:

illKey           = format/our_config/ILLDoubleCheck.ini

18. SiteSearch 4.1.2a includes new database configuration files for all FirstSearch databases demonstrated in the OBI, version 1. Does your WebZ environment include any of these databases?

  • Yes. See Appendix D – New FirstSearch 5 Configuration Files.
    • Compare your 4.1.1 versions of these files to their 4.1.2a counterparts in <NewWebZ_root>/ini/dbs. Decide whether you wish to:
      • use the 4.1.2a versions of these files in <NewWebZ_root>/ini/dbs, as is.
      • copy your current 4.1.1 versions of these files in <WebZWork_root>/ini/dbs to <NewWebZ_root>/ini/dbs.
      • edit the files in <WebZWork_root>/ini/dbs to incorporate the changes in the 4.1.2a versions of these files to your 4.1.1 files.
    • Make sure that the paths to formatting configuration files in the [formats] section of the database configuration files refer to the /our_config directory under <NewWebZ_root>/ini/format.
    • Edit <NewWebZ_root>/ini/databases.ini to refer to the 4.1.2a versions of the FirstSearch 5 configuration files, where applicable.
  • No. Go to step 20.
19. (Optional, but recommended) Move the vendor-specific database configuration files delivered with SiteSearch 4.1.2a to a separate directory under <NewWebZ_root>/ini/dbs, such as /412aship, to retain the shipped versions of these files. If you decided to use one or more of the new FirstSearch 5.0 database configuration files described in step 16, remember to leave copies of these files in <NewWebZ_root>/ini/dbs.

20. Copy the database configuration files that you modified in steps 14-19, along with database configuration files for any other databases, to <NewWebZ_root>/ini/dbs.

Updating and Copying HTML Files

21. Create a new directory under <WebZWork_root>/htdocs for your customized HTML files, such as /our_config. Add /html, /images, /error, and /help subdirectories under this directory.

22. Copy index.html from the directory that contains your customized HTML files in <WebZWork_root> to <NewWebZ_root>/htdocs/our_config.

23. Appendix E contains a list of HTML files modified in SiteSearch 4.1.2a. Have you customized any of these files?

  • Yes. Except for definetopic.html, the only changes made to these files were those for Netscape 6 compatibility. You can find these changes in WebZ Fixes for Netscape 6 Compatibility. If you haven't already made these changes, make them in your 4.1.1 environment in <WebZWork_root>/htdocs.

    For definetopic.html, add the sections shown in Appendix F to <WebZWork_root>/htdocs/our_config/html or <WebZWork_root>/htdocs/obiv/html.

  • No. Go to step 24.
24. Copy all files in the /html, /images, and /error directories under <WebZWork_root>/htdocs/our_config or /obiv1 to the <NewWebZ_root>/htdocs/our_config directories of the same names.
25. Copy or move all Javadoc directories and files under <NewWebZ_root>/htdocs/obiv1/help to <NewWebZ_root>/htdocs/our_config/help.
26. Copy the new HTML files shipped with SiteSearch 4.1.2a (see Appendix E ) from <NewWebZ_root>/htdocs/obiv1/html to <NewWebZ_root>/htdocs/our_config/html.

27. Appendix G contains a list of Java classes modified in version 4.1.2a. Have you modified any of these classes in any way in your 4.1.1 environment?

  • Yes. For each file you have modified:
    • Use the UNIX diff utility (or another utility that can identify the differences between two files) to identify the differences between the 4.1.2a version in <NewWebZ_root> and your customized 4.1.1 version in <WebZWork_root>.

      Note:  

      If you created new class packages for your customized Java classes, compare the 4.1.1 version in the new class package to the 4.1.2a version of the file.


    • Edit the customized class in <WebZWork_root> accordingly.
  • No. Go directly to step 28.
28. Copy all of your customized Java classes to <NewWebZ_root>, creating a directory structure for customized class package(s) as needed.
29. Recompile any class you modified in step 27 in the <NewWebZ_root> environment.

Copying and Converting WebZ Access Database

30. Are you using mSQL as part of your Access component for WebZ?

  • Yes. Go to step 31.
  • No. Are you using a Windows-based SQL database as part of your Access component for WebZ?
    • Yes.
      • Create a dump of the database contents.
      • Rename the database dump file as accessdb.sql.
      • Copy the database dump file to <NewWebZ_root>/accesssql/accessdb.sql.
      • Go to step 33.
    • No. Go to step 34.

31. Select a new port number for mSQL in <WebZWork_root>. (You only need to use this port for the next two steps of this procedure.)

  • Edit <WebZWork_root>/msql/msql.conf to change the value of the TCP_Port variable in the [general] section to the new port number.
  • Edit <WebZWork_root>/ini/servers/AccessServer.ini to change the value of the URL variable in the [JDBC] section to the new port number.

32. In <WebZWork_root>, create a database dump file for accessdb (the WebZ Access database) and copy this file to <NewWebZ_root>/mysql:

  • Start the mSQL server in <WebZWork_root>.
  • From <WebZWork_root>/scripts, enter the following command:
  • msql dump

  • Copy the dump file, <WebZWork_root>/msql/accessdb.dump.Dyyyymmdd.Thhmmss, where yyyymmdd is the current year, month, and day, and hhmmss is the current time, to <NewWebZ_root>/mysql.
  • Rename <NewWebZ_root>/mysql/accessdb.dump.Dyyyymmdd.Thhmmss as accessdb.dump.
  • Stop the mSQL server in <WebZWork_root>.

33. Convert your accessdb database to the 4.1.2a table structure.

  • Go to the <NewWebZ_root>/scripts directory.
  • Edit the $perlPath variable in the updateSQL.pl script so that it contains the path to your Perl interpreter.
  • Enter one of the following commands to load your database dump file into a new database with the 4.1.2a table structure:

    for an mSQL database: perl updateSQL.pl accessdb.dump webz
    for a Windows NT SQL database:   perl updateSQL.pl accessdb.dump webz nt

This updates the accessdb.dump file in <NewWebZ_root>/mysql (UNIX) or <NewWebZ_root>/accesssql. It also creates a copy of the original accessdb.dump file as accessdb.dump.orig. See Changes Made to accessdb Database During Conversion for information about the changes made to the table structure.

You can subsequently configure the Access component for your operating system (click here for UNIX: click here for Windows NT) and then load the data in the accessdb file into the database.

Final Modifications and Testing

34. Are you WebZ in a UNIX environment and using the Apache Web server?

  • Yes. Edit <NewWebZ_root>/httpd/apache_1.3.11/conf/httpd.conf so that it refers to the directory for your customized HTML files, <NewWebZ_root>/htdocs/our_config. Modify these lines so that they read:
    DocumentRoot <NewWebZ_root>/htdocs/our_config
    
    
    ...
    <Directory <"NewWebZ_root>/htdocs/our_config"> ...

    Alias /icons/ <NewWebZ_root>/htdocs/our_config/icons/ <Directory <"NewWebZ_root>/htdocs/our_config/icons/"> ...
    ScriptAlias /cgi-bin/ "<NewWebZ_root>/htdocs/our_config/CGI-bin/"
  • No. Make similar modifications to those for Apache in your Web server's configuration file(s).

35. Test the <NewWebZ_root> environment. Start the Web server, SQL server (if necessary), and the WebZ system. Start a new WebZ user session in a Web browser, and perform several searches. Make sure to check all of the WebZ functionality through the interface, such as:

Debug any problems that have been introduced with this integration using the Troubleshooting the WebZ System document.

36. When you are satisfied that the <NewWebZ_root> environment is functioning properly, make it your new production environment.

WebZ-only sites: Change the Web server port and SQL database port in <NewWebZ_root> to the ports that you use in the production environment. Recall that you modified these ports so that you could upgrade and test the <NewWebZ_root> environment without interfering with your production environment.

  • In a UNIX environment with the Apache Web server, change the Web server port in <NewWebZ_root>/httpd/apache_1.3.11/conf/httpd.conf.
  • In a UNIX environment where you are using MySQL, change the MySQL port in <NewWebZ_root>/mysql/data/my.cnf (port variables in the [client] and [mysqld] section) and <NewWebZ_root>/ini/AccessServer.ini (URL variable in the [JDBC] section).
  • For other Web servers or SQL databases, see the appropriate documentation for port changes or other modifications necessary to make <NewWebZ_root> your new production environment.
Sites with both WebZ and Database Builder: Do not change the Web server port for Record Builder until after you complete the Database Builder upgrade procedure.

37. Are you using Database Builder?

 

Database Builder Upgrade Procedure

This procedure applies only to SiteSearch environments that include Database Builder.

Assumptions:  

(1) You have completed the WebZ upgrade procedure before you start this procedure.

(2) The only modifications you have made to the Record Builder application are to formatting configuration files and templates. If you have modified the Record Builder interface or its underlying Java classes, contact SiteSearch Support before upgrading Record Builder (steps 7 to end).


Note:  

If you are using Record Builder's Save database, make sure that the Save database contains no records in progress when you upgrade. You cannot transfer records from the Save database in SiteSearch 4.1.1 to the Save database in SiteSearch 4.1.2a.

Shutting Down Record Builder

1. Shut down the Record Builder application (click here for the UNIX shutdown procedure; click here for the Windows NT shutdown procedure).

Copying Local Database Files

2. Copy your individual local database directories in the <WebZWork_root>/dbbuilder/dbs directory into <NewWebZ_root>/dbbuilder/dbs. You do not need to copy the Database Builder sample database, localERIC, into the <NewWebZ_root> environment.

3. Verify that you copied your individual local database .ini files from <WebZWork_root>/ini/dbs to <NewWebZ_root>/ini/dbs during step 20 of the WebZ upgrade procedure. You do not need to copy the .ini file for the Database Builder sample database, localERIC.ini, into the <NewWebZ_root> environment.

4. Copy each local database's <WebZWork_root>/dbbuilder/SSDOT/info/dbname.reg file into the <NewWebZ_root>/dbbuilder/ssdot/info/ directory, where dbname is the local database name. This step allows the 4.1.2a SSDOT program to recognize each local database without reregistering each database.

Editing Local Database Information with SSDOT

5. Start the SSDOT program, located in <NewWebZ_root>/dbbuilder/ssdot. Type "l" and press Enter to list the registered databases within the 4.1.2a SSDOT environment. Verify that all of your local databases are recognized in the 4.1.2a environment.

6. Edit the registration information for each local database, changing items 2 through 12 to point to the <NewWebZ_root> environment instead of the <WebZWork_root> environment. Exit SSDOT.

Using Record Builder?

7. Are you planning to use Record Builder?

  • Yes. Go to step 8.
  • No. You have completed this procedure.
Note:  

The rest of this procedure pertains to upgrading Database Builder's Record Builder application. If you do not use or are not planning to use Record Builder, these steps are optional. However, OCLC recommends that all sites upgrade Record Builder to version 4.1.2a so that you have the most recent version available if you subsequently plan to use it.

Copying and Converting Record Builder Access Database

8. Are you using mSQL as part of your Access component for Record Builder?

  • Yes. Change the value of the URL variable in the [JDBC] section of <NewWebZ_root>/ini/AccessServer_rb.ini so that it contains the SQL port number you are using to test the <NewWebZ_root> environment. For mSQL, you changed this port in step 31 of the WebZ upgrade and the syntax of the variable is as follows:
    [JDBC]
    
    SQLDriver=com.imaginary.sql.msql.MsqlDriver
    
    URL=jdbc:msql://bongo:mSQL_port/accessdb
  • No. Are you using a Windows-based SQL database as part of your Access component for WebZ?
    • Yes.
      • Create a dump of the database contents.
      • Rename the database dump file as rbdb.dump.
      • Copy the database dump file to <NewWebZ_root>/accesssql/rbv0.
      • Go to step 10.
    • No. Go to step 11.

9. In <WebZWork_root>, create a database dump file for rbdb (the Record Builder Access database) and copy this file to <NewWebZ_root>/mysql:

  • Start the mSQL server in <WebZWork_root>.
  • From <WebZWork_root>/scripts, enter the following command:
  • msql_rb dump

  • Copy the dump file, <WebZWork_root>/msql/rbdb.dump.Dyyyymmdd.Thhmmss, where yyyymmdd is the current year, month, and day, and hhmmss is the current time, to <NewWebZ_root>/mysql.
  • Rename <NewWebZ_root>/mysql/rbdb.dump.Dyyyymmdd.Thhmmss as rbdb.dump.
  • Stop the mSQL server in <WebZWork_root>.

10. Convert your rbdb database to 4.1.2a format.

  • Go to the <NewWebZ_root>/scripts directory.
  • Ensure that the $perlPath variable in the updateSQL.pl script contains the path to your Perl interpreter.
  • Enter one of the following commands to load your database dump file into a new database with the 4.1.2a table structure:

    for an mSQL database: perl updateSQL.pl rbdb.dump rb
    for a Windows NT SQL database:   perl updateSQL.pl rbdb.dump rb NT

This updates the rbdb.dump file in <NewWebZ_root>/mysql (UNIX) or <NewWebZ_root>/accesssql/rbv0. It also creates a copy of the original rbdb file as rbdb.dump.orig. See Changes Made to rbdb Database During Conversion for information about the changes made to the table structure.

You can subsequently configure the Access component for your operating system (click here for UNIX; click here for Windows NT) and then load the data in the rbdb file into the database.

Updating Customized Database Framework and Formatting Configuration Files

11. Have you modified the template.xml, field.xml, and .dtd files for any local DC(2) databases that you update with Record Builder?

  • Yes. For each local database with customized 4.1.1 versions of template.xml and field.xml, edit these files as follows:
    • Change each occurrence of <RB:scheme> to <DC:Scheme>.
    • Change each occurrence of <RB:modifier> to <DC:Qualifier>.

    Then go to step 12.

  • No. Copy template.xml, field.xml, and dc.dtd from <NewWebZ_root>/dbbuilder/dbs/dc to the local database's top-level directory under <NewWebZ_root>/dbbuilder/dbs, overwriting the 4.1.1 versions of these files. Then go to step 14.

12. Edit the .dtd file for each local database with customized 4.1.1 versions of template.xml and field.xml, as follows:

  • Change the line for RB:scheme to DC:Scheme, but retain the original tag number.
  • Change the line for RB:modifier to DC:Qualifier, but retain the original tag number.

13. Have you modified any of the Record Builder formatting configuration files (/ini/format/rbv0) or interface style configuration files (/ini/interface/rbv0) files listed in Appendix H in your 4.1.1 production environment?

  • Yes. For each file you have modified:
    • Use the UNIX diff utility (or another utility that can identify the differences between two files) to identify the differences between the 4.1.2a version in <NewWebZ_root> and the customized 4.1.1 file in <WebZWork_root>.
    • Edit the file in <NewWebZ_root> accordingly.
    • Then go to step 14.
  • No. Go to step 14.

Testing and Final Modifications

14. Test the Record Builder application in the <NewWebZ_root> environment. Start the Web server, SQL server (if necessary), and Record Builder (click here for the UNIX startup procedure; click here for the Windows NT startup procedure). Start a new Record Builder user session in a Web browser. Make sure to check all of the Record Builder functionality through the interface, such as:

15. When you are satisfied that the Record Builder application in the <NewWebZ_root> environment is functioning properly, make it your production version. Change the Web server port and SQL database port in <NewWebZ_root> to the ports that you use in the production environment. Recall that you modified these ports so that you could upgrade and test the <NewWebZ_root> environment without interfering with your production environment.

  • In a UNIX environment with the Apache Web server, change the Web server port in <NewWebZ_root>/httpd/apache_1.3.11/conf/httpd_rb.conf.
  • In a UNIX environment where you are using MySQL, change the MySQL port in <NewWebZ_root>/mysql/data/my.cnf (port variables in the [client] and [mysqld] section) and <NewWebZ_root>/ini/AccessServer_rb.ini (URL variable in the [JDBC] section).
  • For other Web servers or SQL databases, see the appropriate documentation for port changes or other modifications necessary to make the Record Builder application in <NewWebZ_root> your new production version of this application.


Appendices

The document Appendices for the Upgrade from Open SiteSearch 4.1.1 to SiteSearch 4.1.2a contains each appendix referenced in these procedures. Each appendix includes links to the procedure steps in this document that refer to it.


See Also

Installing the WebZ (Web Server) Extension (Version 4.1.2a)
Installing WebZ (Version 4.1.2a)
Installing Database Builder (Version 4.1.2a)

Description of the Open SiteSearch 4.1.2 Release
Description of the Open SiteSearch 4.1.2a Patch Release
Appendices for the Open SiteSearch 4.1.2a Upgrade


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

Last Modified: