|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
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 utility 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
Options
-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 option 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 option 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 option 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 option below.
-p
Adds support for level-based users and creates or initializes a default set of users and groups. See -p option 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 option below.
-r rps_main rps_text
Specifies the location and name of the repository main file and repository text file. See -r option below.
-d target_dir
Specifies the directory where the system catalog will be created. See -d option 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 option below.
-l log
Creates a log file to record dbcreate messages. See -l option below.
-v
Turns on verbose logging, which includes informational messages in addition to cautions and errors. See -v option below.
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. To preserve existing users when regenerating, include -n in the command. For more information on users, see Managing access with users, groups, and table settings.
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"
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 -a or -p:
- To add support for privilege-based users (including an initial set of users), use -c with -a. See Managing privilege-based users and privileges for information on initial users.
- To add support for level-based users (including an initial set of users and groups), use -c with -p. See Managing level-based users and groups for information on initial users and groups.
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 that file will be made to the system catalog.
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.
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.
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.)
|
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. |
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.
|
|
Do not use the -p option with -a or with a system catalog that supports privilege-based users. This may corrupt the system catalog. |
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.)
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.
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.
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:
- For client/server configurations, the conversion setup file must be on the server.
- If cnv_file includes a filename without a path, dbcreate looks for the file in the current working directory.
- If you specify -i with cnv_file, that setting will be used rather than an SODBC_CNVFIL setting.
- If you specify -i without cnv_file, dbcreate does not use a conversion setup file, even if the SODBC_CNVFIL environment variable is set.
The -i option is effective when used with -c and -x, but not with -u. See -c option and -x option above for more information.
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 file extension. If you don’t specify a path, the file is saved to the current working directory.
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.)
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.
- On Windows and Unix:
dbcreate -c -p -r DATA:rpsmain DATA:rpstext -d TARGET:
- On OpenVMS:
$ DBCREATE -C -P -R DATA:RPSMAIN DATA:RPSTEXT -D TARGET:
The following Windows example creates 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:
