Quayle Consulting Inc.

VMS Migration Tools

Introduction

Quayle Consulting Inc. uses two DCL scripts to automate migration of a physical system to an emulated system.  They work around most of the "gotchas" involved in disk migration.  The scripts are:
The version number of each script is incremented when either script is revised.  There is some interoperability of scripts with previous versions, although such use is not recommended.

This document refers to Version 13 of the tools.  Previous versions may operate differently.

Disclaimer

These tools are provided "as-is" to make the migration of a VMS system to an emulator easier.  Quayle Consulting Inc. does not assume any liability for use of these tools.


Getting the Tools

There are two sources for the tools:

Privileges

The account used to run MIGRATE_SEND needs one of the following privileges to read everything on the physical system's disks: The account used to run MIGRATE_RECEIVE needs VOLPRO to set disk labels.

Both MIGRATE_SEND and MIGRATE_RECEIVE require NETMBX and TMPMBX privileges.

DECnet Migration

Most of the "Initial Preparation" section assumes a DECnet migration.

IP Migration

It is possible to use IP instead of DECnet by one of these methods:

Initial Preparation

The following steps should only have to be done once.
  1. Create an empty container file that is at least 20% bigger than the largest used size of any disk to be migrated.
  2. Configure that container file into the emulator.
  3. Launch the emulator and start VMS.
  4. Initialize and mount the empty container file (DUA80, for example):
    1. INIT DUA80 SCRATCH
  5. Configure DECnet on both the physical system and the emulator.
    1. The physical system probably has DECnet configured already.  To verify that it is present:
      1. SHOW NETWORK
      2. You might have to start DECnet, even if it's configured. (See below)
    2. To set up DECnet on the emulated system:
      1. Edit SYS$SYSTEM:MODPARAMS.DAT, and change SCSSYSTEMID to be the desired DECnet address.  The value is (1024 * DECnet area) + DECnet node.  For example, node 5.47 is a SCSSYSTEMID of 5167.
      2. @SYS$UPDATE:AUTOGEN GETDATA SETPARAMS NOFEEDBACK to put the change into the system image.  It would be a good idea to read the generated report to verify that no serious errors were reported.
      3. Reboot VMS.
      4. @SYS$MANAGER:NET$CONFIGURE (SYS$MANAGER:NETCONFIGURE on older VMS versions).  Set up DECnet to use the same address as used in the first step.
      5. @SYS$MANGER:STARTNET to start DECnet.  The previous step will usually have a prompt to start the network, rendering this step unnecessary.
  6. Add a proxy on the emulated system so that the physical system can write files without a user name and password:
    1. MCR AUTHORIZE
    2. UAF> ADD/PROXY *::* SYSTEM/DEFAULT
    3. UAF> EXIT
  7. Copy the MIGRATE_SEND script to a convenient place on the physical system, and MIGRATE_RECEIVE to a convenient place on the emulated system.

Preparation Before Migration

Having data "in flight" during a migration can make the restored data unusable, and system disks unbootable.  When possible, the following steps should be taken:

Basic Operation

On the physical system, use the following command (assuming node 5.47 in the Initial Preparation section):

    @MIGRATE_SEND 47::

On the emulated system, use the following command:

    @MIGRATE_RECEIVE

Assume that disk DKA200 is being copied.  The following files will be sent to DECnet node 47.
The emulated system must have a device called DISK$SCRATCH to receive the savesets.

Note:  Both of these commands could be written into one-line DCL scripts and then launched as detached processes using MIGRATE_START_DETACH.

Device Names

MIGRATE_SEND attempts to "clean up" the names of the devices being sent to the remote system.  However, it may not be possible to have the same device names on the emulated system.  Device names may also be prefixed with an allocation class value or system name.  In these cases, logical names must be set up before running MIGRATE_RECEIVE.

For example, assume that the physical system is using DSSI disks DIA3 and DIA4, but the emulated system only supports DU devices.  The following logical names will allow the MIGRATE_SEND script to work:

$ DEFINE/SYS/EXEC DIA3 DUA3:
$ DEFINE/SYS/EXEC DIA4 DUA4:

Another example:  The disks being copied are shadow sets.

$ DEFINE/SYS/EXEC DSA10 DKA10:
$ DEFINE/SYS/EXEC DSA40 DKA40:

There is no need that the number part of the physical device name be the same on the emulated system, although it makes the "bookkeeping" simpler.  These mappings will be have to be added to SYLOGICALS.COM on the migrated system disk before booting it.

Note:  Once the migration is complete, scripts such as SYLOGICALS.COM will have to be modified to work with the new device names.  This is especially true when dealing with shadow sets (DSx device type).

MIGRATE_SEND Detailed Documentation

As MIGRATE_SEND processes disks, it changes its process name to "MIG <disk>", where "<disk>" is the disk device being processed.

MIGRATE_SEND accepts the following command-line parameters:
  1. The filespec of the savesets on the remote system.  If not specified, a local copy is performed to DISK$SCRATCH:[000000].  In this case,  the DISK$SCRATCH device is not transferred.  If "?" is specified, documentation is displayed and the script exits.
  2. If specified, only that disk is transferred.  In that case, the SEND_ONLY and SEND_SKIP files are ignored.
  3. If present, backups are done file-by-file.  Otherwise, do image backups.
  4. If specified, the /ALIAS flag is specified.  Otherwise, /NOALIAS is specified.  This option has no effect on file-by-file backups or when the sending VMS version is earlier than 7.0.
  5. (unused, ignored)
  6. If present, create a log file of the backup.  The log file will be written to the default directory.  Its name will be the device name with an extension of .LOG.
  7. If present, compress savesets.  Ignored if not running VMS 8.4 or later.  Warning: do not specify unless receiving system is running VMS 8.4 or later.
  8. P8 has three functions:
    1. If the value is exactly "DEBUG", extended status information is written to SYS$OUTPUT.
    2. If the value is exactly "DRY", a "dry run" is made: no backups are made, but *.SPEC files are written.  Debugging is forced on.
    3. The value is passed to SEND_POST.COM.

Specifying Disks to Send

MIGRATE_SEND allows control over which disks will be sent to emulated system.  The following files, if present in the default directory, control which disks are sent:
If SEND_ONLY.DAT is present, only the disks in the file are sent.  If SEND_ONLY.DAT is not present, the disks in SEND_SKIP.DAT are not sent, but the rest of the disks on the physical system will be sent.

Both files are simple text files, with one device name per line.  Spaces, blank lines, or anything after "!" is ignored.

Post-Processing in MIGRATE_SEND

If file SEND_POST.COM is present in the default directory, it is called after each disk is processed, with the following command-line parameters:
  1. The disk device name
  2. The disk volume label
  3. The log file name from the backup, if one was created by passing a parameter to MIGRATE_SEND.
  4. The full filename of the backup saveset
  5. The full filename of the .SPEC file
  6. The value of P2 as passed to MIGRATE_SEND
  7. The value of P7 as passed to MIGRATE_SEND
  8. The value of P8 as passed to MIGRATE_SEND
If the physical system has an empty "scratch" disk, it would be possible to make the backup go to that scratch disk.  The post-processing script could then FTP the .SPEC and .BCK files to the emulated system using MIGRATE_SEND_FTP.

This capability isn't used too often, since physical systems don't usually have unused disks.

Stopping MIGRATE_SEND

If MIGRATE_SEND_STOP is defined as a GROUP or SYSTEM logical name, the MIGRATE_SEND script will stop after completing the disk that is currently in progress.

Warning:  If the SEND_POST.COM script launches a subprocess, MIGRATE_SEND does not wait for it to complete before exiting.  If MIGRATE_SEND is run as a detached process, the subprocess terminates immediately.

Aborting the MIGRATE_SEND script using any other method, such as STOP/ID, may leave an invalid backup file on the target system.  MIGRATE_RECEIVE may attempt to restore this backup, with unpredictable results.

How It Works

The MIGRATE_SEND script uses the F$DEVICE lexical function to scan the list of devices on the physical system.  It skips the following devices:
For each disk, MIGRATE_SEND creates a .SPEC file that holds the device characteristics:
MIGRATE_RECEIVE detects the presence of a .BCK file.  If it is not zero blocks, it waits until the backup is complete.  At that point, the disk is initialized only if its label is either BLANK or unreadable.  BACKUP is then called to restore the disk, either /IMAGE or file-by-file, depending on the value in the .SPEC file and a parameter passed to MIGRATE_RECEIVE.

The .SPEC file controls how the target disk is to be initialized.

MIGRATE_RECEIVE Detailed Documentation

MIGRATE_RECEIVE accepts the following command-line parameters:
  1. The filespec of the savesets.  The default is DISK$SCRATCH:[000000]*.BCK .
  2. Email address to notify of the backup result.  If not specified, no email is sent.
  3. If present, restores are done file-by-file  Otherwise, the .SPEC file from the sending system controls the restore type.
  4. If present, truncate all sequential files at their end-of-file using BACKUP's /TRUNC switch.  Otherwise, restore the files to their allocated sizes, rounded up to the cluster factor on the emulated system's disk.
  5. If present, do a ANALYZE/DISK on each disk after restore.
  6. If present, do not delete the backup saveset.  If not present, the .BCK file is set to zero blocks to prevent a re-send of the disk.
  7. If present, mount disks /NOWRITE after restore.  If not present, disks will be left mounted for write.
  8. If present, write extended status information to SYS$OUTPUT.  If P8 is "DRY", a "dry run" is made -- no disks are affected.
Disks are restored with highwatermarking enabled, unless logical name MIGRATE_RECEIVE_NOHIGH is defined.

If running on VMS 8.3 or later, the "/REPAIR" switch is used to automatically fix some problems with the backup savesets.  This can fix problems caused by FTP file transfers, which eliminates the need for unsupported attribute-correction programs.

Pre-Processing in MIGRATE_RECEIVE

If file RECEIVE_PRE.COM is present in the default directory, it is called before the saveset is processed, with the following command-line parameters:
  1. The disk device name
  2. The disk volume label
  3. The log file name from the restore, if one was created by passing a parameter to MIGRATE_RECEIVE
  4. The full filename of the backup saveset
  5. The full filename of the .SPEC file
  6. (unused)
  7. (unused)
  8. The value of P8 as passed to MIGRATE_RECEIVE
This is most useful in a FTP migration, where BACKUP saveset attributes are corrupted.  This script, although unsupported, can be be used to correct the attributes before the savesets are restored.

Post-Processing in MIGRATE_RECEIVE

If file RECEIVE_POST.COM is present in the default directory, it is called after each disk is processed, with the following command-line parameters:
  1. The disk device name
  2. The disk volume label
  3. The log file name from the restore, if one was created by passing a parameter to MIGRATE_RECEIVE
  4. The full filename of the backup saveset
  5. The full filename of the .SPEC file
  6. (unused)
  7. (unused)
  8. The value of P8 as passed to MIGRATE_RECEIVE

Special Rule for Volume Sets

Volume sets are always transfered file-by-file, even if the arguments to MIGRATE_RECEIVE specify image backup.  This eliminate the volume set, which is not necessary in a virtual environment.  The disk that is restored is the first device in the volume set.

Special Rule for Shadow Sets

Shadowed disks can be backed up file-by-file or image.  The device that is restored is the first device in the shadow set.  If the receiving system can support shadowing, the resulting disk is mounted as a single-member shadow set (DSA1, DSA2, etc.).  This allows the "DSA" device naming to be retained.  If additional members are required, they can be mounted with a copy operation, using the normal VMS commands to add a member.


MIGRATE_SEND_FTP Detailed Documentation

MIGRATE_SEND_FTP sends all:  .BCK, .SPEC, .ZIP to a remote system using FTP.

MIGRATE_SEND_FTP accepts the following command-line parameters:
  1. The directory holding files on the local system.  If not specified, DISK$SCRATCH:[000000] is used.
  2. The hostname, or IP address, of the target system.
  3. The user name to use on the target system.
  4. The password to use on the target system.  If no password is required, this argument is optional.
  5. Directory on the target system.  If not specified, the default directory on the target is used.
  6. The priority at which to run.  If not specified, zero is used.  Values greater than 4 are not recommended.
  7. If not specified, the backup saveset on the local system is replaced with a zero-length file.  This keeps MIGRATE_SEND from attempting to backup the disk again.
  8. If this parameter is specified, extended status information is written to SYS$OUTPUT.

MIGRATE_START_DETACH Detailed Documentation

MIGRATE_START_DETACH accepts the following command-line parameters:
  1. The name of the script to launch.
  2. The name of the file to receive SYS$OUTPUT output.  Optional.  If not specified, the script's name with an extension of .LOG is used.  Specify "NL:" to suppress any log file.
  3. (unused, ignored)
  4. The process name.  Optional.  If not specified, the first 15 characters of the script name is used.  Specify exactly "NONE" if no name is desired.
  5. Option switches to pass to the command.  Optional. If not specified, "/AUTHORIZE" is used to get the quotas from the SYSUAF instead of the minimum default values from the current SYSGEN parameters.
All other parameters are ignored.

DO_ALL_DISKS Detailed Documentation

DO_ALL_DISKS accepts the following command-line parameters:
  1. The name of the script to run.
  2. Device name.  If specified, only that device is used.  Otherwise, all disks, other than CD-ROM and NFS disks, are processed.
  3. Unused.
  4. Unused.
  5. Unused.
  6. Unused.
  7. Unused.
  8. Unused.
All other parameters are ignored.

For each disk, the script receives the following command-line parameters:
  1. Disk device name, in FULLDEVNAM format.
  2. Reserved for future use.
  3. As passed to DO_ALL_DISKS as parameter P3.
  4. As passed to DO_ALL_DISKS as parameter P4.
  5. As passed to DO_ALL_DISKS as parameter P5.
  6. As passed to DO_ALL_DISKS as parameter P6.
  7. As passed to DO_ALL_DISKS as parameter P7.
  8. As passed to DO_ALL_DISKS as parameter P8.

COMPARE_FILE_DATES Detailed Documentation

COMPARE_FILE_DATES is run on the original system to determine which files have changed since a previous      migration.
Example
Assume that all disks were copied as a proof-of-concept migration on March 31, 2011. Prior to the production migration, COMPARE_FILE_DATES can be run with a date of 2011-03-31 to find which files from each disk need to be copied. The newer file list has each newer file, including the disk name, with one line per file. These are the files that need to be copied. It would be easy to create a script that copies only these files to the virtual system.

COMPARE_FILE_DATES accepts the following command-line parameters:

  1. Disk(s) to check, as a comma-separated list. Default: the current default disk.
  2. Unused.
  3. Date to separate the files, YYYY-MM-DD format. This is the only required parameter.
  4. File name of newer file list. Default: FILE_NEWER.TXT in default directory.
  5. Older file list. Default: FILE_OLDER.TXT in default directory.
  6. If specified, do not skip .DIR and .LOG files. Otherwise, ignore these files.
  7. If specified, check all versions of the files. Otherwise, only check the highest-number version.
  8. If specified, how often to display progress reports. If zero or not specified, no reports are displayed.
Note: DO_ALL_DISKS can be used to automatically process all the files on all disks, with COMPARE_FILE_DATES as the script. In this case, care must be taken to not purge the output files, since they will have the same names, but different version numbers.

ZIP_FILES_BY_DATE


ZIP_FILES_BY_DATE is run on the original system, building ZIP files of the files which have changed since a previous migration.

ZIP_FILES_BY_DATE accepts the following command-line parameters:
  1. Disk(s), as a comma-separated list.  Default: the current default disk.  If "?" is specified, documentation is displayed and the script exits.
  2. (unused, ignored)
  3. Date to separate the files, YYYY-MM-DD format.
  4. The directory in which to put the ZIP files.  Default: the current default directory.
  5. If specified, a delta time to wait between scanning the next file.  Format: hour:minute:second.hundreth.
  6. If specified, do not skip .LOG files.  Otherwise, ignore these files.  ".DIR" files are always skipped.
  7. (unused, ignored)
  8. If specified, how often to create progress reports.  If zero or not specified, no reports are displayed.
For each disk device, a ZIP file is created.  For example, DKA200 generates a file DKA200.ZIP.

If file ZIP_POST.COM exists in the default directory, it is called, receiving the following command-line parameters:
  1. Disk device name, in FULLDEVNAM format.
  2. Name of the ZIP file.
Note:  Symbol "ZIP" must point to the ZIP program.


UNZIP_FILES_BY_DATE


UNZIP_FILES_BY_DATE is run on the virtual system, restoring ZIP files as created by ZIP_FILES_BY_DATE, unzipping them on each disk.

UNZIP_FILES_BY_DATE accepts the following command-line parameters:
  1. The directory which holds the ZIP files.  Default is the current default directory.
  2. (unused, ignored)
  3. (unused, ignored)
  4. (unused, ignored)
  5. (unused, ignored)
  6. (unused, ignored)
  7. (unused, ignored)
  8. (unused, ignored)
UNZIP_FILES_BY_DATE creates a new version of each file that is restored.  It does not specifically copy file owners, protections, or ACL's.  However, VMS usually does the "right thing" because newer versions get the same protections as the previous version.  This is not the case for files which were not present on the original migration.

Note:  Symbol "UNZIP" must point to the UNZIP program.



Contact Us!

We respect your privacy -- you will not be added to a mailing list. Check out our plain-language privacy policy.

If the address fields on this form are not suitable for specifying your address, please fill them with NA and provide your mailing address in the message box.

Required fields are labeled with red italic text.

 

Services

Quayle Consulting Inc. provides a complete menu of services, including:

Quayle Consulting in the news:

Quayle Consulting information:

Interesting items:

Stromasys Partner
HP Certified OpenVMS
          System Engineer
HP Business Partner
Quayle Consulting Inc. on LinkedIn
Trademarks
OpenVMS is a trademark of Hewlett-Packard.
CHARON-VAX and CHARON-AXP are trademarks of Stromasys.
Windows is a trademark of Microsoft Corporation, USA.