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 option; to import, run it with either -i or -if. 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|-i|-if options...
- On OpenVMS, define this symbol:
rpsutl:==$RPS:rpsutl.exe
and then use this syntax:
rpsutl -e|-i|-if 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 option to export (generate) schema. 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.
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] [-t]
Options
-e
Export (generate) a 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.
-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.
-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.
-es [structure[=[k] [a] [r]]]
(optional) Export structure definitions. Default output includes the structure itself, fields, 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.
-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.
-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
-er
(optional) Export all relations. This option is equivalent to the -es structure=r option.
-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.
-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. But default, 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_*
Importing Synergy Data Language files
Run rpsutl with the -i or -if 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, or you can merge new or updated definitions into an existing repository.
|
|
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 wish 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]
Options
-i
Import (load) a 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) a 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.
-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 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.
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
