Migrating from Zim 7.x to Zim 8

This guide describes the process of migrating a database from Zim 7.x to Zim 8. The following steps are required to achieve a successful migration:

a) a) Backup the Zim 7.x database

b) Ensure all Database Objects are Registered Properly in the ZOM Object Dictionary

c) Export the Zim 7.x database

d) Reinstall Zim 8 if necessary

e) Create the New Zim 8 database

f) Update Configuration Files

g) Start Zim Server

h) Run the Database Converter

i) Stop Zim Server

j) Import Data Files from the Zim 7.x Database

k) Import Other Required Files

l) Start Zim Server to Test the New Zim 8 Database

a) Backup the Zim 7.x Database

Even though the migration process does not affect your database, it is a good practice to backup your original database.

b) Ensure all Database Objects are Registered Properly in the ZOM Object Dictionary


1. Start a single-user Zim 7.x session in the original database directory


2. Run the following ZOM commands to list errors and warnings in the original database


> zomenable

> zomdiagnose ;d zomoutputdoc ;b

 

The ZOM diagnose tool will produce a list of warnings and errors in the database. This list contains several headers.

If any of the following headers appear, the reported problems must be solved before the migration process can continue in step 3.

 

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

*** Objects that are not created

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

ObjectType   DirName            ObjectName         OwnerName

 

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

*** Objects that are corrupt and need recreation

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

ObjectType   DirName            ObjectName         OwnerName

 

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

*** Objects named after a reserved word

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

ObjectType   DirName            ObjectName         OwnerName

 

3. Run the following ZOM command to ensure all ZOM database objects are properly registered. Click OK in the dialogue box to start the process

> zomreset *

 

While zomreset is executing, it will report each registered database object:6

 

Touching Object: <name>, <number> to go

 

When the zomreset process completes, you will see the following message:

 

ZOM Activity: Done

 

c) Export the Zim 7.x Database

This procedure exports the definitions in the Data Dictionary to text files and optionally exports existing data.

1. Start a single-user Zim 7.x session in the original database and check whether it is necessary to create a document called zim8cnv1

> list 1 docs where docname="zim8cnv1"

 

If the document exists, skip ahead to step 4.

2. Copy the file zim8cnv1.cmd from the Zim 8 directory to the directory of the original Zim 7.x database


3. Create a document to match the copied zim8cnv1.cmd file

> aft docs
zim8cnv1 zim8cnv1.cmd
> create doc zim8cnv1

 

Or

 

> add docs let docname="zim8cnv1" filename="zim8cnv1.cmd" dirname="ZIM"

> create doc zim8cnv1

4. Create or update the  config.db file (found in the Zim 7.x database directory) and add or update the following configuration options

parameter size 32000
directories <number of Zim directories of your application>
files 100

5. Run the program from the Zim 7.x prompt to export all definitions to the \port directory in the database directory

> zim8cnv1

 

When the program executes, it will ask whether you wish to export the data in the Zim 7.x database to ASCII files:

 

Do you want to download all your data into ASCII documents? (y/n)

 

Exporting the data is only required if the converted Zim 8 database will be hosted in an operating system different from the one that hosted the Zim 7.x database.

Otherwise, there is no need to export the data, since it will remain in the same format.

However, we do recommend exporting the data because it simplifies the migration process, even though it requires more time to complete.

 

If you choose to export the data, then you can skip step j).

WARNING

The export mechanism only exports the definitions of the database, but does not copy files such as dirs.zim and areas.zim.

It is the administrator's responsibility to ensure that these files are correct and to copy them to the appropriated places.

 

5. Write down the values of maximum tables and directories reported after the migration program terminates. They will be used in step f)

6. Exit the Zim 7.x session

d) Reinstall Zim 8 if Necessary

If you are reinstalling a new version of Zim 8, follow these steps:

1. Create a backup copy of zimconfig.srv and zimdb.zim

2. Install Zim 8 in the recommended location, as outlined in Installing Zim 8

3. Move the backup copies of zimconfig.srv and zimdb.zim back to the Zim 8 installation directory

e) Create the New Zim 8 Database

1. Create a Zim 8 database using ZIMINIT ( Unix ) or ZIMINITW ( Windows ).

2. Copy the files from the original Zim 7.x database's \port directory to the new Zim 8 database's \port directory

3. Create or update the zimdb.zim file located in the Zim 8 installation directory.

 

For instance, on Windows, create a database called Ex8 in C:\Databases\Ex8 and copy all the files in the \port directory of the original database to  C:\Databases\Ex8\port in the new Zim 8 database.

f) Update Configuration Files

The database converter reports two values that may need to be changed in configuration files: maximum tables and directories.

1. Change the value of maximum tables in zimconfig.srv if the reported value is larger than the default ( 400 ) or the current value in the file.

The zimconfig.srv configuration file is located in the Zim 8 installation directory.

2. Change the value of directories in zimconfig.zim if the reported value is larger than the default ( 10 ) or the current value in the file.

The zimconfig.zim configuration file is located in the converted database directory. If this file does not exist, you need to create it.

 

For more information on configuration options, visit Types of Configuration Files.

g) Start Zim Server

Start Zim Server as documented in ZIMSERVER.

On Windows, you can also double-click on the Start Zimserver shortcut in the Zim 8 program group:

h) Run the Database Converter

This step cannot be executed without creating a fresh Zim database, as described in step e), and should never be executed twice over the same database.

 

1. Run the database converter program (zim8cnv2) using Zim Thin Client or ZimQt.

zimtc -n <database name> -c zim8cnv2

or

zimqtc -n <database name> -c zim8cnv2

 

If you prefer, start zim8cnv2 from Zim Thin Client or ZimQt's prompt:

zimtc .... -c ""

or

zimqtc .... -c ""

 

Then type:

> zim8cnv2

 

Note: On Windows, you can also start Zim Thin Client or ZimQt and add the Database and Command in a dialog box:

2. Watch the execution of the script. If you encounter an error, proceed to step h). Otherwise, skip to step i)

i) Stop Zim Server

Start Zim Server as documented in ZIMSERVER.

On Windows, you can also double-click on the Stop Zimserver shortcut in the Zim 8 program group:

WARNING

Zim Server should not be running while data files are being imported

j) Import Data Files

If, in step c), you chose not to export the data from the Zim 7.x database, then you have to copy the physical data files to your converted Zim 8 database.

1. Copy the data files named zimxxxx from zim0100 upwards from the Zim 7.x database directory to the directory of the converted Zim 8 database.

WARNING

The internal structure of Zim directories in Zim 8 is different from the previous versions of Zim.  

To avoid compatibility problems, DO NOT copy zimxxxx data files from the Zim 7.x database to the converted Zim 8 database if there are corresponding zimxxxx.ws operating system directories.

 

At this point, these zimxxxx files are still in the format of previous versions of Zim. However, as soon as you start Zim Server again and start using your application, all files will be automatically and silently converted to the Zim 8 format.

 

2. If you want to guarantee a full migration, start Zim Server and manually issue a FIND 1 over all Zim files.

k) Import Other Required Files

If there are any special files in the original Zim 7.x database, such as programs, documents, and images, they must be manually copied into the converted Zim 8 database.

l) Start Zim Server to Test the New Zim 8 Database

Start Zim Server and use ZimQt to connect to the new Zim 8 database. Test all you applications to ensure they are working as before the migration.

✓You have finished the migration process.  You are now ready to run you migrated database applications on ZimQt while connected to the new Zim 8 Zim Server