Imports accounts from other MultiValue implementations to Caché MultiValue.
MVIMPORT backupfile [dirpath [targetpath]] [(code)]
|backupfile||The file containing the information to restore. This is assumed to be in the native “save” format of the originating system (for example, a UniVerse BACKUP). It can contain data for one or more accounts (namespaces).|
|dirpath||Optional — The location in which to restore certain directory files from a jBASE or UniVerse backup (other MultiValue implementations do not have “stray files”). This path is used to store any directories and files that are otherwise skipped because they do not directly relate to a VOC (“stray files”). MVIMPORT examines the backup and determines the lowest point in the tree of directories (the root) for each group of files. MVIMPORT then imports these subtrees into dirpath. If this argument is omitted, the default location for these stray files is platform-dependent. On Windows, MVIMPORT attempts to restore to the original path, so if the backup contains a file K:\stray, MVIMPORT restores them into K:\stray; if there is no K drive, the file goes nowhere and no error is issued. Restoring on a OSX, the file goes into ./~/stray On Windows, when dirpath is included, if the original drive exists, MVIMPORT will use it and ignore the dirpath.|
|targetpath||Optional — The location to import the account to. If this argument is omitted, import into the MGR directory.|
|code||Optional — A letter code governing the operation of MVIMPORT. Available values are A, C, L, M, O, and R.|
MVIMPORT ignores any command line arguments it does not understand and is not prepared to handle.
The MVIMPORT command used to move accounts from other MultiValue implementations to Caché. It does this by taking a backup file created by another MultiValue implementation and restoring it to Caché MultiValue. MVIMPORT supports backups created by UniVerse, jBASE, D3, Reality, MVBase, OpenQM and Power95. The features of MVIMPORT vary according to the type of backup being restored.
When importing a D3 backup, MVIMPORT uses the D3 file definition to determine the formatting for the @ID record created. This formatting determines whether files are listed left justified or right justified, and defines columnar widths.
If an imported file is a single level file, MVIMPORT always imports it as a single level file, regardless of the emulation setting. See CREATE.FILE for information on single level files.
Caché MultiValue does not support OpenQM. When importing an OpenQM backup, the Caché MultiValue emulation is automatically changed to UniVerse.
MVIMPORT is designed to be a restoration utility for migrating legacy MultiValue accounts to Caché. Users should become familiar with Caché administrator facilities for backup, restore, and other administrative functions.
Because MVIMPORT is designed as a migration aid, it only recognizes programs and data when performing its task. Any indices present in backupfile are ignored. Native Caché facilities for indexing need to be used to recreate indices after the import. Caché classes are not created. It is the responsibility of the application developer to create and use Caché classes as needed. You can use PROTOCLASS to create Caché classes corresponding to MultiValue data dictionary definitions.
MultiValue account manipulation requires %Admin_Manage privileges. This is normally associated with the SYSPROG account. For information on the Caché security model, see the Caché Security Administration Guide. For specific information on roles and privileges, please consult the chapter on Roles and the chapter on Privileges and Permissions in the Caché Security Administration Guide.
Letter Code Options
The following code values are supported:
A: (Alternate account name) Prompts for an alternate account name for restoration instead of using the account name that was originally backed up. This takes precedence over the R option.
C: (Case) Forces the account name to upper case. D3 is not case-sensitive; all other MultiValue emulations are case-sensitive. For D3 backups, file names are also forced to upper case.
Lnn: (Label) Specifies the tape label size as nn bytes. This may be needed when the original backup was to tape which was then copied to an operating system file. Usually this value is “L80”.
M: (Merge) If the account exists in Caché, and the file exists in the account, MVIMPORT overwrites existing records if they are in backupfile, and leaves alone existing records that are not in backupfile. Any new records and files in backupfile are also imported.
O: (Overwrite) If the account exists in Caché, MVIMPORT replaces it. The old account will be deleted, then recreated, and its records imported from backupfile.
R: (Rename) If the account exists in Caché, MVIMPORT does not replaces it. Instead, MVIMPORT imports a new account with a new name. The new name will be ExistingName_nn where nn is a sequence counter.
Determining the Account Name
The account name is found on the backup from D3, Reality, MVBase, OpenQM and Power95. For a UniVerse backup, the account name is the last directory name in the file path. jBASE does not provide the account name, so the user will be prompted for an account name at the start of the import.
If the account exists, and the M, O, or R options were not specified on the command line, MVIMPORT prompts for a response. You can respond with the M, O, or R letter code, which have the same effects as the (M), (O), or (R) command line code options. For example:
Account 'DBIHELPDESK' already exists. Enter 'M'erge,'O'verwrite,'R'ename or 'Q'uit:?
MVIMPORT creates a new account, namespace, and database for each account in the backup that does not already exist in Caché. All hash files (for example, database files) are restored to Caché globals in the created account. All non-hash files (for example, OS files in a directory) are restored to the home directory of the account, or as specified by the dirpath argument. MVIMPORT imports all valid directories by default, including empty directories. For details on the relationship between accounts and namespaces, and the naming conventions used for each, refer to “MV Accounts and Caché Namespaces” in Operational Differences between MultiValue and Caché.
If MVIMPORT is merging accounts using the M option, when duplicate record keys exist in Caché and on the import data stream, the Caché values are overwritten.
MVIMPORT always creates a new account in the default location, as a sub-directory of the InterSystems\Cache\Mgr directory. If you want to create the account in any other location (for example, on another disk), then the procedure is as follows:
Prior to the MVIMPORT, create a blank MultiValue account with CREATE-ACCOUNT, specifying an alternate location. For example:
SYSPROG: CREATE-ACCOUNT MYACCOUNT UV E:\data\MYACCOUNT
Run MVIMPORT with the (M) option. This enables you to merge the account on the backup with the already created account.
Errors and Log Files
At the conclusion of a MVIMPORT operation (for all backups except UniVerse):
Caché displays a summary of the number of errors and warnings. MVIMPORT saves the details of these errors and warnings and general restore statistics to an external file. It displays the filename of this error log file to the user.
When MVIMPORT fails to create a namespace and/or a database, it displays an informative error message.
All items found in backupfile are restored to the VOC, unless they already existed in the VOC.
The file IMPORTED.VOC contains all the original VOC contents, regardless of whether or not MVIMPORT restored the items to the VOC. This allows you to see what the VOC looked like before MVIMPORT made decisions on whether or not to apply items to the VOC.
MVIMPORT looks for object code in D3 backups. While this is discarded on Caché because it cannot be used, its presence indicates which files contain compiled code. This fact is used to mark the file as BASIC source for use with Studio.