Regenerating the system catalog

This topic includes the following sections:

Regenerating the system catalog with dbcreate
Regenerating the system catalog with DBA
Preserving views

Typically, you will need to regenerate the system catalog if you have done any of the following:

Manually made changes to the conversion setup file.
Changed the location of the Synergy data tables.
Used Repository to make changes to the repository files.

You may also consider regenerating if you are distributing several system catalogs all based on the same repository definitions. For more information, see Handling a repository shared by multiple databases.

You do not need to regenerate for changes made to tables with DBA. These changes automatically update the relevant catalog files. Rather, regenerating the system catalog may reverse these changes if you’re not careful choosing generation options and fail to use a conversion setup file when necessary.

You can regenerate a system catalog with dbcreate (see below) or with DBA (see Regenerating the system catalog with DBA).

Regenerating the system catalog with dbcreate

To regenerate the system catalog with dbcreate, use the syntax and options listed in Generating a system catalog from the command line (dbcreate). Use the same repository files you used to generate the system catalog, and make sure the target directory is the directory that contains the existing system catalog files. By default, dbcreate uses the -u option, but there are other options that control the ways tables are updated, enable you to initialize users and groups, and enable you to use a conversion setup file. See Examples.

Controlling updates to tables

When you regenerate a system catalog from the command line, there are three options for updating tables: -c, -x, and -u.

Use -c to clear the tables in the system catalog and then regenerate it.
Use -x to overwrite the tables in the system catalog based on changes to the repository.

The difference between -c and -x is that -c creates the system catalog from scratch. It clears the system catalog and then generates a new one from the repository files. If a table in the existing system catalog is not part of the repository, it won’t be part of the new system catalog. In addition, if you use a conversion setup file, all tables marked as OUT are omitted. On the other hand, -x overwrites existing table definitions in the system catalog files only when a change has been made to a table in the repository. If tables have been added to the repository, they are added to the system catalog. If you use a conversion setup file, tables marked as OUT are not overwritten or removed with -x.

Use -u to update the system catalog and add only new tables. Existing tables will not be changed or removed. This is the default setting when you regenerate a system catalog. If you run dbcreate without either -x or -c, it is the same as running dbcreate with -u.

If you regenerate the system catalog after making changes to the repository files, we suggest you use the -c option, which clears the tables in the system catalog before regenerating it. Other options may not fully update the system catalog contents.

Initializing users and groups with dbcreate

Users and groups are not automatically initialized when you regenerate a system catalog. To initialize them as you regenerate, use the -p option for dbcreate. If no users or groups exist for the system catalog, use -p and -n. (The -n option prevents users and groups from being lost. It instructs dbcreate to create user and group system catalog files only if there are none. If there are user and group system catalog files, it prevents dbcreate from making changes to them.) See Generating a system catalog from the command line (dbcreate) for more information on these options.

If you use -p without -n, dbcreate will remove users and groups you’ve added, it will remove modifications you’ve made to users and groups, and it will restore users and group defaults.

For more information, see Initializing users and groups.

Using a conversion setup file

Both the -i option and the SODBC_CNVFIL environment variable affect the way dbcreate uses conversion setup files.

If you set the SODBC_CNVFIL environment variable, dbcreate automatically uses the conversion setup file that this variable is set to. If SODBC_CNVFIL is not set, you must use the -i option (with a filename) to use a conversion setup file. For information on the SODBC_CNVFIL environment variable, see Specifying a conversion setup file (SODBC_CNVFIL).
If you use the -i option without specifying a filename, dbcreate does not use a conversion setup file—even if the SODBC_CNVFIL environment variable is set.
The -i option overrides the SODBC_CNVFIL setting.

For information on creating conversion setup files, see Generating and editing a conversion setup file.

Examples

In the following examples, the repository files are named rpsmain and rpstext and are located in a directory defined by the environment variable DATA. You want the system catalog files to be created in a directory defined by the environment variable TARGET.

Adding a new table definition to an existing system catalog

To add a new table definition to an existing system catalog, create the new structure definition in Repository; then enter one of the following at the command line:

On Windows or UNIX:

dbcreate -u -r DATA:rpsmain DATA:rpstext -d TARGET:

On OpenVMS:

$ DBCREATE -U -R DATA:RPSMAIN DATA:RPSTEXT -D TARGET:

Changing an existing table definition in a system catalog

To change an existing table definition in a system catalog, change the existing structure definition in Repository; then enter one of the following at the command line:

On Windows or UNIX:

dbcreate -x -r DATA:rpsmain DATA:rpstext -d TARGET:

On OpenVMS:

$ DBCREATE -X -R DATA:RPSMAIN DATA:RPSTEXT -D TARGET:

Creating the default user and group files in a specified directory

To create the default user and group files in a specified directory, enter one of the following at the command line:

On Windows or UNIX:

dbcreate -r DATA:rpsmain DATA:rpstext -p -d TARGET:

On OpenVMS:

$ DBCREATE -R DATA:RPSMAIN DATA:RPSTEXT -P -D TARGET:

Creating the default user and group files if they don’t already exist

To create default user and group files in current directory—but only if they don’t already exist, enter one of the following at the command line:

On Windows or UNIX:

dbcreate -r DATA:rpsmain DATA:rpstext -p -n

On OpenVMS:

$ DBCREATE -R DATA:RPSMAIN DATA:RPSTEXT -P -N

Removing a single table from a system catalog

To remove a single table from a system catalog, remove the structure definition in Repository; then enter one of the following at the command line:

On Windows or UNIX:

dbcreate -c -r DATA:rpsmain DATA:rpstext -d TARGET:

On OpenVMS:

$ DBCREATE -C -R DATA:RPSMAIN DATA:RPSTEXT -D TARGET:

Regenerating the system catalog with DBA

We recommend that you use dbcreate instead of DBA to regenerate a system catalog because dbcreate enables you to see messages that document the generation process.

Start DBA from either Synergy Control Panel (in Windows Control Panel) or the command line. See Command line options.

Open the system catalog in DBA. See Opening a system catalog in DBA.

Select Catalog > Generate.

If necessary, change any of the default settings in the Generate System Catalog window. If you want to use a conversion setup file, for example, make sure the Conversion setup field is filled. If you’ve set the SODBC_CNVFIL environment variable, this field is automatically filled with this variable’s setting. For information on options in the Generate System Catalog window, see step 4.

Click OK or press enter.

When the process is complete, press enter.

Unless an error occurs, an information window will open displaying the message “System catalog generated.” If there is an error, a log file (ConvErrs.log) is created in your TEMP directory.

Preserving views

To preserve views in a system catalog when you regenerate, do one of the following:

Use the -u or -x options (rather than -c) when you regenerate the system catalog with dbcreate.
Use the “Only add new tables” option or the “Add new tables and update existing tables” option when using the DBA program.
Write a program that saves view information, and run that program before you regenerate your catalog. Then, after the catalog has been regenerated, use the output from the program to re-create the views. The Connectivity Series distribution includes an example SQL Connection program, exam_saveviews.dbl (in the connect\synsqlx directory), that illustrates this.