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.2.0 environment.

• Bug fixes and enhancements. Go to Question 3.
• Bug fixes only. Go to Applying 4.2.0 Bug Fixes to an Existing SiteSearch Environment.

3. Have you customized SiteSearch in ANY way?

• Yes. Go to Upgrading from Version 4.1.2a to a Complete 4.2.0 SiteSearch Environment.
• No. Install SiteSearch 4.2.0 in a separate environment, as if you are installing the software for the first time. See Installing and Configuring the Open SiteSearch Suite Then test the 4.2.0 installation, as described in Testing the Open SiteSearch Suite Installation. Finally, make 4.2.0 your production 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 also 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.2.0 WebZ component in this directory.

4. Copy the SS4_2_0.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_2_0.jar and SS4_1_2a.jar.

5. Edit your CLASSPATH environment variable to read the SS4_2_0.jar file.

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_2_0.jar: \
<WebZ_root>/classes/lib/mail.jar: \
<WebZ_root>/classes/lib/activation.jar

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.2.0 version of the software.

# What version of SiteSearch is installed
SSVERSION=4_2_0

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

SSVERSION=4_2_0

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
• mysql
  
• 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:

• Interlibrary Loan (ILL)
• record bookmarking, e-mail, and display
• record formats
• browse searching
• advanced searching
• user authorization
• local holdings
• vocabulary-assisted searching (without a thesaurus database)
• combined result sets

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

This procedure uses SiteSearch's ability to version an interface to place your customized configuration files and HTML files in separate directories in your SiteSearch 4.2.0 environment. If you are not already doing this, we suggest that you consider this practice beginning with SiteSearch 4.2.0.

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.

1. Make a copy of your existing 4.1.2a 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.2.0 software.

3. Install all the version 4.2.0 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.

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

• Use the UNIX diff utility to identify the differences between the .ini files in <WebZWork_root>/ini and <NewWebZ_root>/ini. The only files with changes in SiteSearch 4.2.0 are JaSSIServer.ini and databases.ini.
• Make a copy of the files that you need to update in <NewWebZ_root>/ini in a separate directory, such as <NewWebZ_root>/ini/420ship.
• 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 this new line in the [JaSSI] section: #UTF8EncodeInput = false (2) Do not remove or modify this new section: #[InterfaceLanguages] #default = interface/obiv2/en/langBase.ini #en = interface/obiv2/en/langBase.ini (3) 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. (4) Add any class packages you have created for customized Java classes to the [PackageOrder] section. (5) Edit the [servername] section to reflect the threshold values you used in your 4.1.2a production environment.

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

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

8. Copy your server configuration files (including database-specific and ILL files) <WebZWork_root>/ini/servers to <NewWebZ_root>/ini/servers.

9. Add the following line to <NewWebZ_root>/ini/servers/ZBase.ini in the list of all other variables at the bottom of the file:

#SupportsUTF8=false

10. Move your customized formatting configuration files from <WebZWork_root>/ini/interface/our_config (where our_config is the directory that contains your customized files) or /obiv1 to <NewWebZ_root>/ini/format.

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

11. If you are using the ABIIFormats.ini or FSInspecFormats.ini formatting configuration files, see Appendix A for modifications to these files in SiteSearch 4.2.0. Edit these files in <NewWebZ_root>/ini/format/our_config accordingly.

12. 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"

15. Copy your database configuration files from <WebZWork_root>/ini/dbs to <NewWebZ_root>/ini/dbs.

16. Appendix B contains a list of database configuration files modified in SiteSearch 4.2.0 and the changes to these files. Have you modified any of these files in your 4.1.2a environment?

• Yes. Edit any file affected in <NewWebZ_root>/ini/dbs accordingly.
• No. Go directly to step 17.

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

21. Are you using a frames-based interface?

• Yes. Edit <NewWebZ_root>/htdocs/our_config/html/imageworkframe.html. Replace the colon preceding "&context;" with a question mark, as follows:

<frameset cols="20%,80%" frameBorder="yes" border="1">
   <frame src="&StyleTable.DEFAULTS.NAMESPACE;html/ \
      imagenav.html?&context;" name="imagenav">
   <frame src="&StyleTable.DEFAULTS.NAMESPACE;html/ \
      image.html?&context;" name="images">
</frameset>

• No. Go directly to step 22..

22. Appendix C contains a list of Java classes modified in version 4.2.0. Have you modified any of these classes in any way in your 4.1.2a 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.2.0 version in <NewWebZ_root> and your customized 4.2.0 version in <WebZWork_root>.
  
  

  Note:

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

  
  
• Edit the customized class in <WebZWork_root> accordingly.
• No. Go directly to step 23.

25. Are you using MySQL as part of your Access component for WebZ?

• Yes. Go to step 26.
• 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 28.
  • No. Go to step 29.

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

• Edit <WebZWork_root>/mysql/data/my.cnf to change the value of the TCP_Port variable in the [client] and [mysqld] sections 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.

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

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

mysql dump

• Copy the dump file, <WebZWork_root>/mysql/accessdb.dump.Dyyyymmdd.Thhmmss, where yyyymmdd is the current year, month, and day, and hhmmss is the current time, to <NewWebZ_root>/mysql.
• Rename the sample accessdb.dump file in <NewWebZ_root>/mysql with another name of your choice.
• Rename <NewWebZ_root>/mysql/accessdb.dump.Dyyyymmdd.Thhmmss as accessdb.dump.
• Stop the MySQL server in <WebZWork_root>.

28. Configure the Access component for your operating system (click here for UNIX: click here for Windows NT). Load the accessdb.dump file that contains your Access database into the accessdb database.

29. 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).

30. 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:

• Interlibrary Loan (ILL)
• record bookmarking, e-mail, and display
• record formats
• browse searching
• advanced searching
• user authorization
• local holdings
• vocabulary-assisted searching (without a thesaurus database)
• combined result sets

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

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

32. Are you using Database Builder?

• Yes. Go to the Database Builder upgrade procedure.
• No. You have completed the upgrade procedure.

(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 10 to end).

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.2a to the Save database in SiteSearch 4.2.0.

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 15 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 SSDOT for Newton to recognize each local database without reregistering each database.

5. Start SSDOT for Newton, located in <NewWebZ_root>/dbbuilder/ssdot. Type "l" and press Enter to list the registered databases within the 4.2.0 SSDOT environment. Verify that all of your local databases are recognized in the 4.2.0 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.

7. Are you interested in downloading and configuring one or more new Pears demonstration databases available from the SiteSearch 4.2.0 site? (You can also do this later if you wish.)

• Yes. Go to step 8.
• No. Go to step 10.

8. On the FTP site, go to the Sitesearch/4.2.0/DbBuilder/dbs-pears directory. Each subdirectory contains a .tar file that contains the files necessary to set up a demonstration database and a README file.

• Download the .tar files for the database(s) of your choice.
• Follow the instructions in the README file for uncompressing the .tar file and moving the files to the appropriate directories in the <NewWebZ_root> environment

10. Are you planning to use Record Builder?

• Yes. Go to step 11.
• No. You have completed this procedure.

11. Are you using MySQL 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 MySQL, you changed this port in step 26of the WebZ upgrade and the syntax of the variable is as follows:

[JDBC]
SQLDriver=org.gjt.mm.mysql.Driver
URL=jdbc:mysql://hostname:port/rbdb

• No. Are you using a Windows-based SQL database as part of your Access component for Record Builder?
  • 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 13.
  • No. Go to step 14.

12. 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 MySQL server in <WebZWork_root>.
• From <WebZWork_root>/scripts, enter the following command:

mysql_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 the sample rbdb.dump file in <NewWebZ_root>/mysql with another name of your choice.
• Rename <NewWebZ_root>/mysql/rbdb.dump.Dyyyymmdd.Thhmmss as rbdb.dump.
• Stop the MySQL server in <WebZWork_root>.

13. Configure the Access component for your operating system (click here for UNIX: click here for Windows NT). Load the data in the rbdb.dump file that contains your Record Builder Access database into the rbdb database.

14. Edit the .dtd file for every database you update with Record Builder, following this example from the sample DC2 database framework shipped with Record Builder. Note the new line and words in dark blue bold text.

Change this:

Attribute             2
ID                 1099
....
PCDATA             1001

To this:

rec                   0 RecordTag
Attribute             2 attribute
ID                 1099
PCDATA             1001 content

15. Modify the path for all variables in the Record Builder database configuration files in <NewWebZ_root>/ini/dbs so that these variables refer to directories in <NewWebZ_root>/dbs rather than <WebZWork_root>/dbs. These variables include:

16. Add these sections to each Record Builder configuration file in <NewWebZ_root>/ini/dbs. These sections allow you to use Record Builder's new single-record import and export capabilities.

For DC(2) or DCQ databases:

[Export]
recordsyntax = SGML
dbdescfile =

[Import]
recordsyntax = SGML
dbdescfile =

[HandleSGML]
tagsfile = <NewWebZ_root>/dbbuilder/dbs/db_name/db_name.dtd
newLinesAfterEveryField=true

Substitute the appropriate directory and file name for /db_name/db_name.dtd.

For MARC databases:

[Export]
recordsyntax = MARC
dbdescfile =

[Import]
recordsyntax = MARC
dbdescfile =

17. 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 D in your 4.1.2a 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.2.0 version in <NewWebZ_root> and the customized 4.1.2a file in <WebZWork_root>.
• Edit the file in <NewWebZ_root> accordingly.
• Then go to step 14.
• No. Go to step 14.

18. 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:

• adding, modifying, and deleting records
• browsing for records
• using the Save database
• user authorization

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