Main -> Documentation -> Product Updates -> Upgrading to Open SiteSearch 4.0.1

Upgrading to Open SiteSearch 4.0.1

This document provides upgrade instructions describing how to integrate the Open SiteSearch 4.0.1 software release into an existing SiteSearch environment on UNIX systems. If you have NOT customized your existing SiteSearch environment at all, install the 4.0.1 software into your <WebZ_root> directory. Otherwise, carefully follow the directions in this document to install the new version of the software while preserving your changes to WebZ.

WARNING: If you have customized your SiteSearch environment, DO NOT install the 4.0.1 software package into your existing environment. You will lose all of your changes by installing 4.0.1 on top of an existing environment.

Note:

If you are a SiteSearch 4.0.0 user who has not upgraded to 4.0.0a, you only need to upgrade to 4.0.1, which includes all of the bug fixes and functionality included with the 4.0.0a release.

Requirements

Before completing the instructions in this document, you must

Document Conventions

  • <Backup_root> refers to a backup directory for the current version of the software that you are using (4.0.0 or 4.0.0a) where you can safely make corrections while allowing patrons to continue to access the <WebZ_root> environment during the upgrade.
  • <previous_version> refers to the current version of the software that you are using (4.0.0 or 4.0.0a).
  • <TempDir_root> refers to the temporary directory where you installed the Open SiteSearch 4.0.1 software.
  • <WebZ_root> refers to your existing Open SiteSearch 4.0.0/4.0.0a environment.

Upgrade Instructions

Follow the appropriate instructions below based on the amount of functionality you want to obtain with SiteSearch 4.0.1 and the amount of time you want to spend upgrading your existing SiteSearch environment. OCLC recommends that you upgrade to a complete 4.0.1 environment.

Applying 4.0.1 Bug Fixes to an Existing SiteSearch Environment

The following procedure describes how to integrate 4.0.1 bug fixes into an existing 4.0.0/4.0.0a environment with the SS4.0.1.jar file. By completing the steps below, you will only receive the bug fixes that have been made to the SiteSearch software with the 4.0.0a and 4.0.1 releases. To integrate the complete 4.0.1 software package with an existing environment, refer to Upgrading to a Complete 4.0.1 Environment.

1. Backup your existing 4.0.0/4.0.0a 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.

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

3. Copy the SS4.0.1.jar file located in the <TempDir_root>/classes/lib directory into the <WebZ_root>/classes/lib directory. There should now be two files located in the <WebZ_root>/classes/lib directory, SS<previous_version>.jar and SS4_0_1.jar.

4. Edit your classpath environment variable to read the SS4.0.1.jar and the SS<previous_version>.jar file. Your classpath should look like the following (in this exact order):

.:<fullpath to JDK>/lib/classes.zip
<fullSystemRoot>/classes/: \
<fullSystemRoot>/classes/lib/SS4_0_1.jar: \
<fullSystemRoot>/classes/lib/SS<previous_version>.jar
Note:

<fullSystemRoot> is the full path to the <WebZ_root> directory. <fullpath to JDK> is the location of your JDK installation. The backslash ("\") characters are included for readability and should NOT be added to the CLASSPATH setting.

After you have edited the CLASSPATH variable, logout of your UNIX session and log back in to activate the new settings.

5. Edit the ssmgr.hostname file located 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. The following items need to be changed to reflect the 4.0.1 version of the software.

Above the "DO NOT edit below this line" statement:

    # What version of SiteSearch is installed
    SSVERSION=4_0_1
    

Below the "DO NOT edit below this line" statement (in this exact order):

    CLASSPATH="$JAVAHOME/lib/classes.zip:$ROOTDIR/classes:$ROOTDIR/
    classes/lib/SS$SSVERSION.jar:$ROOTDIR/classes/lib/
    SS<previous_version>.jar"
    Note:

    <previous_version> is the previous version of the jar file that you also defined in your classpath. The 4.0.1 jar file is referenced in this definition as ":$ROOTDIR/classes/lib/SS$SSVERSION.jar".

Save and close the ssmgr.hostname file.

6. Edit the ssadmin file located in the <WebZ_root>/scripts directory in a text editor. The following items need to be changed to reflect the 4.0.1 version of the software:

SSVERSION=4_0_1
CLASSPATH="$JAVAHOME/lib/classes.zip:$ROOTDIR/classes:$ROOTDIR/
classes/lib/SS$SSVERSION.jar:$ROOTDIR/classes/lib/
SS<previous_version>.jar"
Note:

<previous_version> is the previous version of the jar file that you also defined in your classpath. The 4.0.1 jar file is referenced in this definition as ":$ROOTDIR/classes/lib/SS$SSVERSION.jar". Make sure to reference the parts of the CLASSPATH variable in the exact order shown above.

Save and close the ssadmin file.

7. Start the Web server, SQL server (if necessary), and the WebZ system.

8. Test the 4.0.1 integration with your existing environment. 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:

  • ILL
  • record bookmarking, e-mail, and display
  • record formats
  • browse searching
  • advance searching
  • user authorization
  • local holdings

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

Upgrading to a Complete 4.0.1 Environment

The following procedure describes how to integrate the modifications you made to the 4.0.0/4.0.0a environment into a new 4.0.1 environment. It is important to follow the instructions below carefully to preserve the changes you have made to the SiteSearch software. Print out these instructions and use them as a checklist for upgrading your environment. Refer to Product Updates for descriptions of the software upgrades which are included in the 4.0.1 package.

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

1. Backup your existing 4.0.0/4.0.0a environment in a separate directory (<Backup_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 <Backup_root> directory. Restart the Web server, SQL server, and WebZ system. You will use the <Backup_root> directory to upgrade your 4.0.1 enviroment, while still providing patron access to the <WebZ_root> environment until the upgrade is complete.

2. Create a temporary directory (<TempDir_root>) and install all of the 4.0.1 SiteSearch components that you have licensed in this temporary directory.

Note:

This temporary directory will become your new <WebZ_root> environment after you have completed these upgrade instructions.

3. Edit your classpath environment variable for the 4.0.1 environment. Your classpath must contain the following information:

.:<fullpath to JDK>/lib/classes.zip: \
<fullSystemRoot>/classes/: \
<fullSystemRoot>/classes/lib/SS4_0_1.jar
Note:

<fullSystemRoot> is the full path to the 4.0.1 <TempDir_root> directory. <fullpath to JDK> is the location of your JDK installation. The backslash ("\") characters are included for readability and should NOT be added to the CLASSPATH setting.

After you have edited your classpath variable, logout of your UNIX session and log back in to activate the new settings.

4. Compare the <TempDir_root>/ini/interface/defaultStyle.ini configuration file with the interface style configuration files you have implemented in the <Backup_root>/ini/interface directory. Use the UNIX diff utility to document the differences between these files, updating your 4.0.0/4.0.0a files with the changes.

5. Implement the new target structure for all frames-based WebZ interfaces by adding a [targets] section to each of your <Backup_root> interface style configuration files. By completing steps 5 and 6, entity references will replace standard target references in all of the HTML files. The following is an example of the [targets] section which is included in the 4.0.1 defaultStyle.ini file:

#This is especially for a frames based interface.
#For a non-frames interface, delete the targets 
#section and the targets will not be inserted 
#into your HTML pages.

[targets]
homePage        = target="_top"
BookMark        = target="bookmark"
mainFrame       = target="main"
searchResults   = target="main"
scanResults     = target="main"
defineTopics    = target="main"
searchPage      = target="main"
recordDisplay   = target="workframe"
scantermDisplay = target="scanterms"
bookmarkDisplay = target="workframe"
ILL             = target="workframe"
email           = target="workframe"
imageDisplay    = target="new"
imageNav        = target="imagenav"
images          = target="images"

After you have made all of the changes to your interface style configuration files, move the files from your existing environment into the <TempDir_root>/ini/interface directory.

6. Complete one of the following two tasks for frames-based interfaces only:

Warning: All of the HTML files have changed with the 4.0.1 software to allow for an easier transition to frameless interfaces. As part of this implementation, target references have been removed from HTML files and placed in the interface style configuration files as entity variables (as described in step 5).

  • If you made minor changes to your 4.0.0/4.0.0a HTML (i.e., you have only changed the colors of the interface with a few minor HTML changes), add these modifications directly to the 4.0.1 environment. Use the UNIX diff utility to identify the minor differences between the <Backup_root> and the <TempDir_root> HTML files.
  • If you have made major modifications to your 4.0.0/4.0.0a HTML files (i.e., you have re-designed each HTML page in the WebZ Out-of-the-Box Interface), you will need to change all of the target references used in customized HTML files in your <Backup_root> environment to entity references. You do not need to make these changes to unmodified HTML files in your <Backup_root> environment.
  • Refer to the following example from dblist.html:

    <FORM METHOD="POST" ACTION="/WebZ/TopicQuery:&context;" 
    target="frame1">

    You must replace all target references (e.g., target="frame1") with an entity reference using the [targets] section of the interface style configuration file (see step 5). The entity reference should have the following standard format based on the interface style configuration file:

    &StyleTable.targets.variable;

    The example from dblist.html shown above is a target reference to the search results screen. The appropriate 4.0.1 entity reference for this example would be:

    &StyleTable.targets.searchResults;
    

    which references the StyleTable (derived from interface style configuration file), [targets] section, searchResults variable. The entire HTML line now reads:

    <FORM METHOD="POST" ACTION="/WebZ/TopicQuery:&context;" 
    &StyleTable.targets.searchResults;>

    Replace all of the target references with entity references for customized HTML files in your 4.0.0/4.0.0a environment using the example shown above. Copy each revised HTML file with the appropriate entity references into the correct htdocs/ subdirectory within the <TempDir_root> environment.

7. Copy your customized database and server configuration files located in the <Backup_root>/ini/dbs directory into the <TempDir_root>/ini/dbs directory. Copy the <Backup_root>/ini/databases.ini file into the <TempDir_root>/ini directory.

8. Use the diff utility to identify the remaining differences between the <Backup_root>/ini directory and the <TempDir_root>/ini directory. Refer to Appendix A: Configuration File Changes for a list of the revised 4.0.1 configuration files. Add any 4.0.0/4.0.0a modifications you have made directly into the <TempDir_root>/ini directory.

9. Identify any formatting classes that you have customized (new formatting class) or modified (made changes directly to an existing class). You will need to replace any HTML target references within the formatting classes with entity references as described in steps 5 and 6 above. (Refer to Appendix B: Formatting Class Changes for a list of revised 4.0.1 formatting classes.)

10. If your customized formatting classes use the addBookMark()method, you must change the parameters used in this method. Refer to the following source examples in:

  • ORG.oclc.fmts.WebZFormatter
  • protected final void addBookMark(int recno, String nextPage)

    protected final void addBookMark(int recno, String nextPage, String otherInfo)

Refer to the sample invocation in:

Note:

The full record invocation will NOT re-FETCH the record since it is already in memory. This is a performance enhancement.

Copy these revised classes into the <TempDir_root> environment and re-compile each class.

11. Use the diff utility to identify any other differences between any modified formatting classes in the <Backup_root> environment and the corresponding 4.0.1 formatting classes. Make any adjustments necessary to your existing classes, copy them into the <TempDir_root> environment, and re-compile the classes.

12. Verify that you have now copied each customized or modified formatting class to the <TempDir_root> environment and have re-compiled each class.

13. If you are using the Access component and mSQL to provide authorization through the WebZ interface, move your mSQL database (accessdb) from <Backup_root>/msql/bin to <TempDir_root>/msql/bin, replacing the sample database that is shipped with the SiteSearch software.

14. (Database Builder and Imaging Support Package only) Copy your individual local database directories located in the <Backup_root>/ini/dbs directory into <TempDir_root>/ini/dbs. You do not need to copy the Database Builder sample database, localERIC, into the <TempDir_root> environment.

15. Copy each local database's <Backup_root>/dbbuilder/ssdot/info/dbname.reg file into the <TempDir_root>/dbbuilder/ssdot/info/ directory, where dbname is the local database name. This step allows the 4.0.1 SSDOT program to recognize each local database without re-registering each database.

16. (Database Builder and Imaging Support Package only) Copy the ber2txt utility located in the <TempDir_root>/scripts directory into the <TempDir_root>/dbbuilder/bin directory.

17. (Database Builder and Imaging Support Package only) Start the SSDOT program located in the <TempDir_root>/dbbuilder/ssdot directory. Type "l" and press Enter to list the registered databases within the 4.0.1 SSDOT environment. Verify that all of your local databases are recognized in the 4.0.1 environment.

18. (Database Builder and Imaging Support Package only) Edit the registration information for each local database, changing items 2 through 12 to point to the <TempDir_root> environment instead of the <Backup_root> environment. Exit SSDOT.

19. (Imaging Support Package only) Copy the <Backup_root>/dbbuilder/ssimage/TYPES directory into the <TempDir_root>/dbbuilder/ssimage directory.

20. (Imaging Support Package only) Run setupinstall.sh by typing "setupinstall.sh" at the UNIX command prompt and pressing ENTER in the <TempDir_root>/dbbuilder/ssimage directory.

21. Run the ssimage_admin.sh program by typing "ssimage_admin.sh" and pressing Enter in the <TempDir_root>/dbbuilder/ssimage/ directory.

22. (Imaging Support Package only) Modify home directory settings for the Imaging Support Package by selecting menu item 4, "Modify ISP System Settings." Verify that the all of the system directory settings reference the <TempDir_root> environment. Make corrections to the directory settings if necessary.

23. (Imaging Support Package only) Edit the directories associated with each collection by selecting menu item 3, "Modify an Existing Collection," in the ssimage_admin.sh main menu. Verify that the directory settings for each collection reference the <TempDir_root> environment. Exit ssimage_admin.sh after you have made all of the corrections to the information for each collection.

24. (Imaging Support Package only) Copy the individual image collection subdirectories one at a time from the <Backup_root>/dbbuilder/collects directory into the <TempDir_root>/dbbuilder/collects directory to move the necessary collection information to your 4.0.1 environment.

Note:

Do not move the sample collection directories for CARC and ERES to the 4.0.1 environment. These collections have been revised with the 4.0.1 release.

25. (Imaging Support Package only) Copy the individual image collection subdirectories one at a time from the <Backup_root>/dbbuilder/delete directory into the <TempDir_root>/dbbuilder/delete directory to move the necessary collection information to your 4.0.1 environment.

Note:

Do not move the sample collection directories for CARC and ERES to the 4.0.1 environment. These collections have been revised with the 4.0.1 release.

26. (Imaging Support Package only) Copy the individual image collection subdirectories one at a time from the <Backup_root>/dbbuilder/locked directory into the <TempDir_root>/dbbuilder/locked directory to move the necessary collection information to your 4.0.1 environment.

Note:

Do not move the sample collection directories for CARC and ERES to the 4.0.1 environment. These collections have been revised with the 4.0.1 release.

27. Test the new 4.0.1 <TempDir_root> environment. Start the WebZ 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:

  • ILL
  • record bookmarking, e-mail, and display
  • record formats
  • browse searching
  • advance searching
  • user authorization
  • local holdings

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

28. After thoroughly testing the <TempDir_root> environment and making any necessary corrections, stop the <WebZ_root> system and bring up the <TempDir_root> system to replace it.

Appendix A: Configuration File Changes

The following configuration files have been revised with SiteSearch 4.0.1. Compare existing 4.0.0/4.0.0a configuration files located in the <Backup_root>/ini directory with these 4.0.1 files.

<TempDir_root>/ini

    AccessServer.ini

    JaSSIServer.ini

<TempDir_root>/ini/dbs

    AcadIndx.ini

    DRA.ini

    DRAHoldings.ini (new file)

    Endeavor.ini

    Horizon.ini

    OPACGroup.ini

<TempDir_root>/ini/interface

    defaultStyle.ini (significant changes)

    redStyle.ini (significant changes)

    rssStyle.ini (new file)

<TempDir_root>/ini/servers

    Access.ini

    DRA.ini

    EBSCO.ini

    ERL.ini

    Endeavor.ini

    FirstSearch.ini

    GEAC_Advance.ini

    Horizon.ini

    IAC.ini

    III.ini

    ILLService.ini

    MultiLIS.ini

    Notis.ini

    Ovid.ini

    Sirsi.ini

    Removed: OclcILL.ini

<TempDir_root>/ini/loc (new directory)

Appendix B: Formatting Class Changes

The following formatting classes have been revised with SiteSearch 4.0.1. Compare any formatting classes that you have customized or modified with the following classes to ensure that they work with the 4.0.1 software.

ORG.oclc.fmts.FormatBerUtil
ORG.oclc.fmts.WebZFormatter
ORG.oclc.fmts.obi.ArchivebriefFmt
ORG.oclc.fmts.obi.ArchivefullFmt
ORG.oclc.fmts.obi.ArchivemultiFullFmt
ORG.oclc.fmts.obi.DRAHoldingsSearchKey (new)
ORG.oclc.fmts.obi.MarcArticleBriefFmt
ORG.oclc.fmts.obi.MarcArticleFmt
ORG.oclc.fmts.obi.MarcArticleMultiFullFmt
ORG.oclc.fmts.obi.MarcCatalogBookmarkFullFmt
ORG.oclc.fmts.obi.MarcCatalogBriefFmt
ORG.oclc.fmts.obi.MarcCatalogFmt
ORG.oclc.fmts.obi.MarcCatalogMultiFullFmt
ORG.oclc.fmts.obi.MarcContentsFrstMultiFullFmt
ORG.oclc.fmts.obi.MarcOvidMultiFullFmt
ORG.oclc.fmts.obi.MarcPapersFrstMultiFullFmt
ORG.oclc.fmts.obi.NetFirstbriefFmt
ORG.oclc.fmts.obi.ReservebriefFmt
ORG.oclc.fmts.obi.ReservefullFmt
ORG.oclc.fmts.obi.ReservemultiFullFmt

See Also

Description of Open SiteSearch 4.0.1
Product Updates
Description of the Open SiteSearch 4.0.0a Patch



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

Last Modified: