dbcreate utility

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS

The dbcreate utility enables you to generate a system catalog and initialize user and group access. See Generating the system catalog for information on system catalog generation. For examples, see Examples below.

You can run dbcreate from the command line on Windows, UNIX, or OpenVMS. The dbcreate program is in the connect subdirectory of the main Synergy/DE installation directory.

To generate the system catalog from scratch, use this syntax:

dbcreate -c -p|-a [option] [...]

To update an existing system catalog, use the following syntax and see Notes on regenerating the system catalog:

dbcreate -x|-u [option] [...]

To see a list of dbcreate options, use this syntax:

dbcreate -?|-h
Note

You should use either -c, -x, or -u in each dbcreate command. If you use -c, you should also use either -p or -a to indicate which type of user the system catalog will support. To preserve existing users when regenerating, include -n in the command.

-c

Generates the system catalog from scratch — i.e., removes any existing system catalog files and creates new system catalog files from the repository. See -c below.

-x

Updates the system catalog. New structures are added to the system catalog as new tables. Tables for changed structures are updated. See -x below.

-u

Adds new structures as new tables in the system catalog, but does not update tables that are already part of the system catalog. See -u below.

-a

When used with -c, this option adds support for privilege-based users or restores the initial set of privilege-based users. See -a below.

-p

Adds support for level-based users and creates or initializes a default set of users and groups. See -p below.

-n

Prevents changes to existing users and groups, but allows default users (and groups or privileges) to be created if they don’t exist. See -n below.

-r rps_main rps_text

Specifies the location and name of the repository main file and repository text file. See -r below.

-d target_dir

Specifies the directory where the system catalog will be created. See -d below.

-i [cnv_file]

When used with cnv_file, this specifies a conversion setup file (to change table access levels, exclude tables from the system catalog, or add tables back into the system catalog). See -i below.

-l log

Creates a log file to record dbcreate messages. See -l below.

-v

Turns on verbose logging, which includes informational messages in addition to cautions and errors. See -v below.

Discussion

Dbcreate options can be in any order, but each dbcreate command should include one of these options: -c, -u, or -x. If you use -c, you should also include either -p or -a to specify whether the database will have privilege-based users or level-based users and groups. For more information on users, see xfODBC security: managing access.

On OpenVMS, the dbcreate utility is set up as a verb. So if you pass more than eight parameters to dbcreate, you must enclose the parameters in quotes. Each option counts for one parameter, and each path specification counts for one parameter. The following command, for example, has nine parameters, so they must be enclosed in quotes:

$ DBCREATE "-C -P -R DATA:RPSMAIN DATA:RPSTEXT -D CAT: -l LG.TXT"

-c

The -c option causes the system catalog to be generated from scratch — i.e., it removes existing system catalog files in the target location and creates new system catalog files from the repository. If the system catalog is generated to a directory that already contains system catalog files, those files will be overwritten. The -c option should be used with either -p or -a:

To preserve existing users and privileges or existing users and groups, include the -n option in the command.

If you use a conversion setup file, changes specified in the conversion setup file will be made to the system catalog.

-x

The -x option updates a system catalog. If the repository has new structures, they are added to the system catalog as new tables. If the repository has structures that are different than the corresponding tables in the system catalog, those tables are updated. System catalog files for privilege-based users are not affected if you use this option. If you use -p, level-based default users and groups will be restored, eliminating any custom users and groups unless you also use -n.

If you use a conversion setup file, tables marked as OUT are not changed or removed. Settings in the conversion setup file are applied for tables marked as IN.

-u

The -u option adds new structures as new tables in the system catalog. Tables that are already part of the system catalog are not updated. System catalog files for privilege-based users are not affected if you use this option. If you use -p, level-based default users and groups will be restored, eliminating any custom users and groups unless you also use -n.

Conversion setup file settings are ignored with -u.

-a

The -a option is for use with -c. It adds support for privilege-based users (i.e., for users and privileges managed with GRANT and REVOKE statements) or restores the initial set of privilege-based users. If you are regenerating a system catalog that already has support for privilege-based users, using -a will eliminate any change you've made to users, unless you also use -n. (Privilege-based user files are not affected when dbcreate is used with -x or -u.)

Important

Do not use the -a option with -p or with a system catalog that supports level-based users and groups. This may corrupt the system catalog.

-p

The -p option is for use with -c. It adds support for level-based users and creates or initializes a default set of users and groups. If level-based users and groups already exist, this option restores default users and groups, eliminating any changes you've made to users and groups, unless -n is also used.

Important

Do not use the -p option with -a or with a system catalog that supports privilege-based users. This may corrupt the system catalog.

-n

The -n option prevents changes to existing users and groups, but enables dbcreate to create default users and groups if they don’t already exist. With level-based users, this is effective with -c, -x, and -u. With privilege-based users, this is effective only with -c. (Privilege-based user files are not affected by -x or -u.)

-r

The -r rps_main rps_text option specifies the location and name of the repository main file and repository text file. If specified, this option overrides RPSMFIL, RPSTFIL, and RPSDAT settings. If not specified, dbcreate uses RPSMFIL, RPSTFIL, and RPSDAT to locate repository files.

-d

The -d option specifies the directory where the system catalog will be created. If not specified, the system catalog will be created in the working directory.

-i

When -i is used with cnv_file, it specifies the conversion setup file to use. When regenerating a system catalog, a conversion setup file enables you to exclude tables from the system catalog (or add them back in) and change table access levels. To use a conversion setup file, you need to generate the conversion setup file and then either use the -i option in the dbcreate command or set the SODBC_CNVFIL environment variable before running dbcreate. See Generating and editing a conversion setup file for more information, and note the following:

The -i option is effective when used with -c and -x, but not with -u. See -c and -x above for more information.

-l

The -l option creates a log file for dbcreate messages. (If -l is not used, messages are printed to the screen.) By default, -l logs only cautions and errors. For verbose logging, use -v with -l.

Log specifies the path (optional) and filename for the log file. Include the filename extension. If you don’t specify a path, the file is saved to the current working directory.

-v

The -v option turns on verbose logging, which includes information messages in addition to cautions and errors. When used with -l, logging messages are written to a file; otherwise, they are written to the screen. (Note that if you use -v with -u or -x and a conversion setup file, the log incorrectly indicates that conversion setup file settings are applied. Instead, none are applied if used with -u. If used with -x, only settings for tables marked as IN are applied.)

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. The system catalog files will be created in a directory defined by the environment variable TARGET, and the system catalog will support level-based users. For more examples of commands that update the system catalog, see Notes on regenerating the system catalog.

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

The following Windows example, however, will create a system catalog that supports privilege-based users:

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

The next example adds tables for any new repository structures, but doesn’t change any existing tables:

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

This example adds tables for new structures and updates tables for structures that have changed in the repository:

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