Regenerating the system catalog

This topic includes the following sections:

 

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

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.

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.

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 instructs dbcreate to create user and group system catalog files if there are none. if there are user and group system catalog files, it instructs dbcreate not to make changes to them.) See Generating a system catalog from the command line (dbcreate) for more information on these options.

Important

Initializing users and groups removes users and groups you’ve added, removes modifications you’ve made to users and groups, and restores users and groups to their default settings.

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.

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:

dbcreate -u -r DATA:rpsmain DATA:rpstext -d TARGET:
$ 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:

dbcreate -x -r DATA:rpsmain DATA:rpstext -d TARGET:
$ 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:

dbcreate -r DATA:rpsmain DATA:rpstext -p -d TARGET:
$ 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:

dbcreate -r DATA:rpsmain DATA:rpstext -p -n
$ 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:

dbcreate -c -r DATA:rpsmain DATA:rpstext -d TARGET:
$ DBCREATE -C -R DATA:RPSMAIN DATA:RPSTEXT -D TARGET:

Regenerating the system catalog with DBA

Note

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.

1. Start DBA from either Synergy Control Panel (in Windows Control Panel) or the command line. See Command line options.
2. Open the system catalog in DBA. See Opening a system catalog in DBA.
3. Select Catalog > Generate.
4. 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.
5. Click OK or press enter.
6. 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: