Sablime® Database Conversion Guide

Sablime^® Database Conversion Guide

Sablime^® version 6.0u3
August 2004

[Introduction] [Preparation] [Running the Conversion] [Post-Conversion Activities] [Getting Help]

What This Guide Covers

This guide provides instructions for converting your Sablime® database from v5.0, v5.1 or v5.2 to v6.0. All versions of Sablime® v6.0 use the same database: there is no database change required for upgrading from v6.0 to v6.0u3 (i.e. update3). So if you already have v6.0 (any version) running, then you do not need to use this guide.

This guide and instructions are only needed for converting a pre-v6.0 database for use with v6.0 (any version).

If you are converting from a version earlier than v5.0 you must convert to v5.0 first. We supply the instructions for the conversion from v4.0, v4.1, v4.2 or v4.3 to v5.0.

Preparation

All conversion activities are done on the Sablime® host machine. Be sure to log in as the Sablime® database owner.

Install Sablime^® v6.0 Binaries
The conversion script needs to access both the old and the new binaries. Make a new directory on the host machine for the new binaries, e.g.,

mkdir v6.0bin

Download the v6.0 binaries and unpack them in the new directory. Install the license file as v6.0bin/.usrid, and do

cd v6.0bin; ksh ./setperm; cd ..

to set the permissions on the binaries. If you want to use the location of the previous Sablime® binaries for the new Sablime® binaries, you need to wait until after the database conversion to move the binaries. (See Post-Conversion Activities, below.)

Converting Multiple GDB's
The conversion script deals with Sablime® products under a single global database (GDB). If you have more than one GDB, you will need to carry out the following steps for each GDB separately. It is usually simplest to convert all the products in one GDB before moving on to the next GDB.

Scheduling Conversion
Products are converted one at a time. The amount of time required to convert a product depends on the size of the product. The actual conversion is usually faster than the audit and backup steps. Users will not have access to products while they are being converted, so plan accordingly and notify users in advance about the expected downtime.

Converting Multiple Products
Generally it is easiest for you and your users if you convert all the products in the GDB before bringing any of them back on line. Limitations of time or space may force you to convert and make available each product one by one. Be aware that if you do this, converted and unconverted products will reside in different GDB's, and will be accessed by different Sablime® binaries. Running the products from a new GDB will impact the xsablime script and other files, and may affect users at other sites, if their products communicate with your products. (See Post-Conversion Activities, below.)

Note Current Version
The conversion script will attempt to identify the version of your current Sablime® release (i.e., v5.0, v5.1, or v5.2), and will then ask you to confirm this. Note the version ahead of time, by running

what $sabLCB/edput | grep Sablime

or by invoking a Sablime® command in screen mode (e.g. pts prompt=y) and noting the version number at the top of the screen.

Stop Databases
The conversion script will stop each product database as it comes to it, but for best results with the audit and backup steps below, we recommend stopping each product (via dbstop) before auditing it, and stopping all the products in the GDB before backing up the databases.

Clean Databases
It is important to make sure your database is "clean" before converting it.

Run the database audits (dbcross, dbdelta, and dbxcross) and make sure that there are no errors before converting your database to the newer release.
If you have any directories in your database whose names begin with "OLD_", be sure to remove these before doing the backup or conversion.

Backup
We recommend that you make your own backup of the Active, Inactive, Global, and Source databases before doing the conversion. The conversion script backs up the records it changes, but this only covers rollbacks needed during the conversion process. To roll back after you have started using the converted database, you will need the full backup.

Running the Conversion

Again, all conversion activities are done on the Sablime® host machine. Be sure to log in as the Sablime® database owner.

Environment Setup
Set to a generic in the product you are going to convert:

. sablime generic

If you are going to convert multiple products in a GDB, set to a generic in any of the products.

Conversion Script
Invoke the conversion script by running

v6.0bin/sab6.0conv

The script will prompt for which product(s) to convert. The script will create a directory .6.0ConvDir under $sabGDB/tmp. The files in this directory track the progress of the conversion. This directory and its files are removed by the post-conversion cleanup script; make sure not to alter them or remove them by hand.

Interrupting and Restarting
If the script is interrupted while converting a product, you may invoke the script again to continue the conversion. Do not try to use the product until you have completed the conversion, or rolled it back.

Rolling Back
You may roll back a partially or fully converted product by running

v6.0bin/sab6.0rollbk

The script will prompt for which product(s) to roll back. If you decide to roll back after you have started using the converted product, you will need to restore the database from the backup you made rather than using the rollback script.

Post-Conversion Activities

Cleanup Script
After all products in the GDB have been converted, run

v6.0bin/sab6.0cleanup

Moving the gdb
After running the cleanup script, you may delete the old gdb. At this point we recommend that you rename the new gdb to have the name of the old gdb. This is optional, but doing so will reduce the amount of editing needed in the xsablime script and elsewhere.

Moving the binaries
After you have converted all your products (in every GDB), we recommend that you rename bin directories so that the new bin has the original name, e.g.

mv bin bin.old; mv v6.0bin bin

This is optional, but doing so will reduce the amount of editing needed in the sablime and xsablime scripts and elsewhere. The PR records in the converted GDB are pointing at v6.0bin, so you will need to correct them to point at the original bin. (The fifth field in each PR record points at the Sablime® bin.)

Any time you move or rename the bin directory, be sure to edit the PR records in the GDB, so that each product will be pointing at the right location.

Updating the sablime and xsablime scripts
Update the sablime.sh and xsablime.sh scripts in the new Sablime® bin and run sh2x on each one:

sh2x sablime.sh sablime; sh2x xsablime.sh xsablime

If you have changed the location of the Sablime® bin or global database, be sure to update the information if you import it from the old sablime or xsablime file.

$sabVAR files
If you use a $sabVAR file to store environment information for one or more of your products, update the contents if you have changed the location of the Sablime® bin or global database. If you kept any $sabVAR files in your old Sablime® bin, move them to the new bin.

Files for External MR Communication
If you are using the Sablime® external MR communication feature, there will be files in your old Sablime® bin called .BIN and .EMR. Copy these to the new Sablime® bin. If you have changed the location of the Sablime® bin or global database, edit the files to reflect the new locations, and notify the administrators for the remote Sablime® instances you communicate with to update their .BIN and .EMR files as well.

Other updates
If you have changed the location of the Sablime® bin, update your PATH to point at the new location. Your users will also need to do this.

Checking the databases
It is recommended to run the audit scripts again before restarting the databases. You may find errors where there were no errors before. In most cases, this is because the audits in Sablime® v6.0 find more errors than the audits in the older releases. If in doubt, contact the Sablime® helpdesk at sablime@lucent.com.

Restarting databases
To restart each product database, set to a generic in the product and run dbstart.

Getting Help

If you get stuck, contact the Sablime® helpdesk at sablime@lucent.com.