Upgrading your federated database to new catalogs

Printer-friendly version

Terms used and their meanings

fd – federated database
db - database
old catalogs – pre-R9.0 internal database format
new catalogs – R9.0 or later version’s internal database format

Reason to upgrade

Starting from Release 11.3, support for the old catalog format is no longer available. R11.2.x is the last release of Objy that is backwards compatible with dbs using old catalogs.

Identify if you are using old catalogs

You will most likely have fds or dbs with old catalogs if you created them using a pre-R9.0 version of Objy/DB. You can be using an R9.0 or later version of Objy/DB but still use old catalog fds or dbs.

How to check if you have old catalog fds or dbs

If you are not sure whether the fds or dbs are using old catalogs or new catalogs, you can determine that by using one of these two methods below:
  1. Run oofile on the fd or any individual database files, to see the release with which they are compatible.
    If the output displays: Compatible with Objectivity release 5 through 11
            The fd or db is using old catalogs.
    If the output displays: Compatible with Objectivity release 9 or later
            The fd or db is using new catalogs.
  2. Write a utility program that calls isR9catalog() on a handle to the fd or an individual database.
    If the API call returns 0,
            The fd or db is using old catalogs.
    If the API call returns 1,
            The fd or db is using new catalogs.

How to upgrade from old catalogs to new catalogs

Once you identify the fd or dbs using old catalogs, you can upgrade them to the new catalog format by following the steps below:
  1. Make a full backup of the fd. Example of a full basic backup:
    oobackup –full
  2. Run oocheck on the boot file to check for inconsistencies and make sure no errors are present. If you run into any errors, please contact Objectivity Customer Support for assistance. For example:
  3. Upgrade the internal catalog format of the fd or db by running the ooupgrade tool and you will see the message:
    Upgrade successfully completed 

    Use one of these following options to upgrade the fd or db:
         Upgrades an entire federated database in a single operation. For example:
    ooupgrade –all 
         Upgrades a federated database, one database at a time.
         Upgrades the system db.
         Upgrades a specific database in the fd.

For your convenience, a support tool is available, which checks the fd and dbs if they contain old catalogs. The tool prints out the fd/db names and ids for the ones that still use old catalogs.

To use the tool, copy the executable to the project folder. To run the tool using command prompt, you must call the executable and pass the bootfile as a parameter. The results will print to the screen, which is convenient for an fd with a small number of dbs.

Example: checkoldcatalogs.exe MyFd.boot
You will see something similar to:
Database ID      Database Name
7                Apple
9                Orange
If the fd is using old catalogs, you will see an output similar to this:
Federated Database ID: 1
Federated Database Name: phonebook
All Databases contain old catalogs and need to be upgraded.
Note: A new catalog fd can contain new catalog dbs and old catalog dbs, but an old catalog fd can only contain old catalog dbs.

An optional parameter may be passed with the name of the file to write the old catalog information out to. If the file does not exist, it gets created, but if the file exists, it will be overwritten. This method is preferred for an fd with a large number of dbs. The results will be saved to the file.

Example:checkoldcatalogs.exe hello.boot catalogs.txt
You will see no output on the screen, and the table of results can be viewed by opening the file.

You may download the tool executable from this link: checkoldcatalogs.exe

The source code is available below.
#include <iostream>
#include <ooObjy.h>
#include <fstream>

using namespace std;

const int BOOTFILE = 1;
const int FLAG = 1;
const int OUTFILE = 2;

int main(int argc, char* argv[])
	FILE *file;
	bool fileparam = false;

	if (argc < (BOOTFILE+1)) 
		fprintf(stderr, "\n** Error: Missing required command line parameter\n\t \"bootFilePath\".\n");
			"Usage: \n"
			"     -help\n"
			"     bootFilePath\n"
			"     [outFilePath]\n"
		return 0;

	string flag = argv[FLAG];

	if (flag.compare("-help") == 0)
		"\nChecks whether the Objectivity/DB has old catalogs and prints the id and names of the files that need to be upgraded\n\n" 
		"     bootFilePath\tPath to the boot file\n"
		"     [outFilePath]\tName of file you wish to save old catalog report to\n"
		return 0;

	if (argc == (OUTFILE+1))
		file = fopen(argv[OUTFILE], "w"); //opens the txt file passed as the second argument
		fileparam = true;

		file = stdout;

		// Used as an indicator if there are old catalogs
		bool hasOld = false; 

		ooConnection *connection = ooObjy::getConnection(argv[BOOTFILE]); // Gets the bootfile path from the first argument
		ooSession *session = connection->createSession("main session");

		ooHandle (ooFDObj) fd = session->fd();
		ooItr (ooDBObj) dbItr;

		// If the fd uses old catalogs, it means the databases, if present, uses old catalogs too 
		if (!fd.isR9catalog())
			fprintf(file, "\nFederated Database ID: %u\nFederated Database Name: %s\n", fd.oid().get_DB(), fd.name()); // Writes the FD ID and FD Name to file
			if(dbItr.next()) fprintf(file, "All Databases contain old catalogs and need to be upgraded.\n");
			if (fileparam) fclose(file);
			return 0;

		fprintf(file, "\nDatabase ID      Database Name\n"); 
		fprintf(file, "-------------------------------------------------------------------------------\n");

		// While you have databases in the fd
		while (dbItr.next())
			dbItr.open(oocRead); // Open a db to check format
			if (!dbItr.isR9catalog()) // If it's NOT R9 Catalog
				fprintf(file, "%-11d      %-60s\n", dbItr.oid().get_DB(), dbItr.name());
				hasOld = true;

		// All catalogs are new
		if (!hasOld)
			fprintf(file, "\nAll fds and dbs are using new catalogs.\n");


	catch ( const ooException & ex )
		fprintf(stderr, "exception in main: %s\n", ex.what());

	if (fileparam) fclose(file);

	return 0;
For more information, please refer to Chapter 3 of the R10.2.1 Release Notes, which can be viewed from this link: http://support.objectivity.com/docs/objectivity/10_2_1/release-notes/pdf