Instead of using the Generate Repository Schema utility and the Load Repository Schema utility, you can run the rpsutl.dbr utility from the command line to generate (export) and load (import) Synergy Data Language files. See Synergy Data Language for more information about Synergy Data Language and possible uses for repository schema files.
|
Unloading a repository to schema and then reloading it into a new repository oftentimes resolves unusual repository errors of unknown origin. |
To export, run rpsutl with the -e or -esf option; to import, run it with either -i, -if, or -isf. See Exporting Synergy Data Language files or Importing Synergy Data Language files for the available options for these two operations.
- On Windows and Unix, use this syntax:
dbr rpsutl -e|-esf|-i|-if|-isf options...
- On OpenVMS, define this symbol:
rpsutl:==$RPS:rpsutl.exe
and then use this syntax:
rpsutl -e|-esf|-i|-if|-isf options...
|
When rpsutl ends, if it encountered errors, it will exit with a status of D_EXIT_FAILURE (1 on Windows and Unix; 0 on OpenVMS). Otherwise, it will exit with a status of D_EXIT_SUCCESS (0 on Windows and Unix; 1 on OpenVMS). Most operating systems have commands that enable you to test for the exit status. See the documentation for your operating system for more information. |
Exporting Synergy Data Language files
Run rpsutl with the -e or -esf option to export (generate) schema. Using -e, you can export all repository definitions, export only certain types of definitions (formats, templates, structures, etc.), or export specific formats, templates, structures, etc., using the options below. When -esf is used, the schema is generated to separate files, one for each repository definition.
rpsutl -e sdl_file [-d main_file text_file] [-em [format]] [-et [template]] [-es [structure[=[k] [a] [r]]]] [-ef [file[=[s] [k] [a] [r]]]] [-ee [enumeration]] [-er] [-nh] [-t]
or
rpsutl -esf [-ed export_dir] [-d main_file text_file]
Options
-e
Export (generate) repository schema.
sdl_file
Specify a Synergy Data Language file to create to hold the schema. The maximum length of sdl_file is 255 characters. If you don’t specify an extension, it defaults to .ddf. If the file already exists, an error is generated.
-esf
Export (generate) repository schema to separate files, one for each repository definition. By default, the files will be created in the current directory. No headers will be included in the files when using -esf. Existing files will be overwritten.
-ed export_dir
(optional) Specify the name of the directory into which the separate schema files will be generated. The maximum length of export_dir is 255 characters.
-d main_file text_file
(optional) Specify the names of the repository main and text files from which to generate the schema. If not specified, the defaults are used, following the logic discussed in Determining the repository files used.
-em [format]
(optional) Export format definitions. The default is to export all. To export a single format, specify it by name. See the Usage section below for information on using wildcards to export multiple formats. If used with -esf, this option is ignored.
-et [template]
(optional) Export template definitions. The default is to export all. To export a single template, specify it by name. See the Usage section below for information on using wildcards to export multiple templates. If used with -esf, this option is ignored.
-es [structure[=[k] [a] [r]]]
(optional) Export structure definitions. Default output includes the structure itself, fields, structure-specific formats, and tags. Additional output can include keys (k), aliases (a), and relations (r). Structure may be an alias structure. The default is to export all structures. To export a single structure definition, specify it by name. See the Usage section below for information on using wildcards to export multiple structures. If used with -esf, this option is ignored.
-ef [file[=[s] [k] [a] [r]]]
(optional) Export file definitions. Default output includes file information only. Additional output can include structures (s), keys (k), aliases (a), and relations (r). Options k, a, and r are valid only if s is present. The default is to export all files. To export a single file definition, specify it by name. See the Usage section below for information on using wildcards to export multiple files. If used with -esf, this option is ignored.
-ee [enumeration]
(optional) Export enumeration definitions The default is to export all. To export a single enumeration, specify it by name. See the Usage section below for information on using wildcards to export multiple enumerations. If used with -esf, this option is ignored.
-er
(optional) Export all relations. This option is equivalent to the -es structure=r option. If used with -esf, this option is ignored.
-nh
(optional) Suppress the generation of the header (comment) block at the top of the generated schema file. This makes it possible to use schema files more effectively with version-control change tracking. See Synergy Data Language file header for more information about file headers.
-t
(optional) Include in the schema the MODIFIED keyword and the date/time the structure was last modified. If you manually edit the schema, you should update this value for any structures that you change. See STRUCTURE for more information. If used with -esf, this option is ignored.
-h
Display usage screen.
The variables for exporting specific elements in the repository (format, template, structure, file, enumeration) can include the wildcard characters * and ?. For example, to export all enumerations beginning with “color_”, you would specify -ee color_*.
If you want to use the s, k, a, or r options and export all structures or files, specify * before the equal sign. For example, to export keys, aliases, and relations for all structures, you would specify -es *=kar. To export assigned structures for all files, specify -ef *=s.
The following example exports all definitions from the repository located in MYDICT:rpsmain.ism and MYDICT:rpstext.ism into the file mySchema.sdl.
dbr rpsutl -e mySchema.sdl -d MYDICT:rpsmain.ism MYDICT:rpstext.ism
The following example exports the structure CUSMAS from the default repository into the file custStruct.sdl. By default, structure-specific formats, fields, and tags are included; adding =kar specifies that keys, aliases, and relations should also be exported.
dbr rpsutl -e custStruct.sdl -es CUSMAS=kar
The following example uses wildcard characters to export selected formats and enumerations from the default repository into the file mySchema.sdl. Formats with names such as NUM1_FORMAT, NUM2_FORMAT, etc. will be exported, along with all enumerations beginning with “COLOR_”.
dbr rpsutl -e mySchema.sdl -ef NUM?_FORMAT -ee COLOR_*
The following example exports all definitions from the default repository into separate files in the MYDICT folder.
dbr rpsutl -esf -ed MYDICT:
Importing Synergy Data Language files
Run rpsutl with the -i, -if, or -isf option to import (load) schema. The definitions to import may be in a single Synergy Data Language file or in multiple files. You can use this option to create a new repository, merge new or updated definitions into an existing repository, or replace an existing repository completely.
|
|
If ISAMC_REV is set to 4, rpsmain and rpstext files are created using the pre-version 10 repository format and, if merging schema, files are not converted to version 10 format. This enables you to target Synergy/DE 9 with Synergy DBL Integration for Visual Studio (SDI). |
|
Rpsutl attempts to load all the definitions in a schema file into the repository. If your file contains definitions you do not want to load, you must remove them from the file before running rpsutl. For example, if your file contains both new and existing definitions, and you want only to update the existing ones, you must remove the new definitions from the file. |
rpsutl -i sdl_file [...] [-d main_file text_file] [-ia] [-io]|[-ir] [-n new_main new_text] [-l [log]] [-r [sec]] [-s]
or
rpsutl -if input_file [-d main_file text_file] [-ia] [-io]|[-ir] [-n new_main new_text] [-l [log]] [-r [sec]] [-s]
or
rpsutl -isf -id import_dir [-d main_file text_file] [-l [log]] [-r [sec]]
Options
-i
Import (load) repository schema from one or more Synergy Data Language files.
sdl_file […]
Specify one or more Synergy Data Language files to use for creating or merging a repository. The maximum number of files is 30, and the maximum length of sdl_file is 255 characters. (If you have more than 30 files or they comprise more than 255 characters, use the -if option instead.) If you don’t specify an extension, it defaults to .ddf. On Unix, wildcard specifications such as *.sdl are supported.
If you specify multiple Synergy Data Language files, all are processed as a single unit. If a specified file cannot be found, no further files will be processed, and, for a merge, the current repository will not be replaced.
-if
Import (load) repository schema from a text file containing a list of Synergy Data Language files.
input_file
Specify a text file containing a list of Synergy Data Language files to use for creating or merging a repository. In the input file, put each SDL filename on a separate line. There is no limit on the number of SDL files you can include in the input file. All files are processed as a single unit. If a specified file cannot be found, no further files will be processed, and, for a merge, the current repository will not be replaced.
-isf
Import (load) repository schema from a set of separate .sdl files.
-id import_dir
Specify the name of the directory from which the separate repository schema files will be loaded. Only files with an .sdl extension will be loaded. Their content will replace the specified repository files.
-d main_file text_file
(optional) Specify the names of the repository main and text files into which definitions will be loaded or merged. If the repository does not exist, it will be created (and will subsequently be deleted should any errors occur). If not specified, the defaults are used, following the logic discussed in Determining the repository files used.
-ia
Add new structures, files, templates, formats, and enumerations. Specify this option to create a new repository by importing the formats in sdl_file. The -ia option must be specified when the schema file contains new definitions. You can also use -ia with either -io or -ir to import into an existing repository and add new definitions while also overlaying or replacing existing ones.
|
|
At least one import option (-ia, -io, -ir) must be specified when you run rpsutl -i. |
-io
Overlay attributes of existing structures, files, templates, formats, and enumerations. Use this option when you want to replace only a subset of attributes or add to those of an existing definition. The -io option updates existing attributes and adds new ones, but does not delete any. Either -io or -ir must be specified when the schema file contains existing definitions; these two options can also be used with -ia as described above. The -io option is not valid when importing into a new repository and is not valid with -ir.
-ir
Replace existing structures, files, templates, formats, and enumerations. Use this option when you want to delete the existing definition and replace it with the definition of the same name in the schema file. Either -ir or -io must be specified when the schema file contains existing definitions; these two options can also be used with -ia as described above. The -ir option is not valid when importing into a new repository and is not valid with -io.
-n new_main new_text
(optional) Specify the names of the temporary repository main and text files to be used when importing into an existing repository. If not specified, the names rpsmain.new and rpstext.new, are used by default. See the Usage section below for more information on temporary files.
-l [log]
(optional) Specify that errors generated during schema loading should be logged to a file named log. If log is not specified, the default filename is SCHEMA.LOG, and the log file is placed in the current working directory. If the -l option is not specified at all, errors will be directed to standard output.
-r [sec]
(optional) Specify that if the repository is being modified by another user, rpsutl should retry the operation after waiting sec seconds. If sec is not specified, the default retry time is 10 seconds. Rpsutl will retry indefinitely if -r is specified. If -r is not specified, rpsutl does not retry, and you’ll receive a “files in use” error.
-s
(optional) Suppress replacement of the repository. Specify this option if you do not want the temporary repository files (see Usage below) to be renamed. The -s option is useful when doing a test or trial import. If you are satisfied with the results, you can rename the files manually.
-h
Display usage screen.
When definitions are imported (merged) into an existing repository, they are actually imported into a copy of the repository, named rpsmain.new and rpstext.new by default. (You can specify different temporary filenames with the -n option.) If no errors occur during the import process and the -s option is not specified, the temporary files are renamed to the original repository filenames. (If -s is specified, both temporary and original files are retained.) If any errors occur, the temporary files are deleted.
When importing definitions from separate files (-isf), the copy of the repository is always named rpsmain.new and rpstext.new, and if no errors occur during the import process, those files are always renamed to the original repository filenames.
On OpenVMS, you must set system option #35 in order for all versions of the original files to be renamed.
|
|
We strongly recommend that when merging a repository, both the original files and the temporary (merged) files be on the same drive on the same system. In some cases, failing to do this results only in slower performance. In other cases (such as when the original files are on Windows and the temporary files on Unix), the procedure fails with a rename error. |
The following example imports the definitions from the files dict1.sdl and dict2.sdl, adding them into the repository specified by newmain.ism and newtext.ism. If the repository does not exist, it will be created. If it does exist, the definitions will be imported to a copy of the repository, rpsmain.new and rpstext.new. If no errors occur, the rpsmain.new and rpstext.new files will replace the newmain.ism and newtext.ism files. If errors occur, they will be logged to the file SCHEMA.LOG, and the .new files will be deleted.
dbr rpsutl -i dict1.sdl dict2.sdl -ia -d newmain.ism newtext.ism -l
The following example is the same as the one above, but rather than list the SDL files individually on the command line, we list them in the file myRPSdefs.txt and then use the -if option:
dbr rpsutl -if myRPSdefs.txt -ia -d newmain.ism newtext.ism -l
The following example imports the definitions from the file order.sdl into the default repository, replacing the existing definitions of the same name. Because -s is specified, if no errors occur, the copied repository, rpsmain.new and rpstext.new, will not be renamed to the default repository. If errors occur, they will be logged to standard output, and the .new files will be deleted.
dbr rpsutl -i order.sdl -ir -s
The example below imports the definitions in customer.sdl into the default repository; new definitions are added and existing ones are replaced. The temp repository files used during the import will be named main.tmp and text.tmp. If the import is successful, they will be renamed to the default filenames. If errors occur, they will be logged to standard output, and the .tmp files will be deleted.
dbr rpsutl -i customer.sdl -ia -ir -n main.tmp text.tmp
The example below imports the definitions from all files with an .sdl extension found in directory c:\project\schema into repository files rpsmain.new and rpstext.new. If no errors occur, the rpsmain.new and rpstext.new files will replace the main.ism and text.ism files.
dbr rpsutl -isf -id c:\project\schema -d main.ism text.ism
